From zzaia-workspace
Orchestrate architectural documentation via pull request with BDD, SDD, plan, and work-item creation using Specification Driven Design
npx claudepluginhub zzaia/zzaia-agentic-workspace --plugin zzaia-workspace--project <name> [--selected-work-item <id>] [--selected-repo <name>] [--selected-branch <name>] [--target-branch <name>] [--description <text>] [--workspace <path1;path2>] [--doc <path1;path2>] [--url <url1;url2>]commands/workflow/remote/## PURPOSE Orchestrate architectural documentation and work-item hierarchy creation for a selected work item using Specification Driven Design (SDD). All documentation is committed to a documentation-only branch with pull request review gates at every phase. Decomposes requirements through BDD analysis, architectural design, and agile planning into a parallelizable hierarchy of work items. Enables human and agent collaboration through Azure DevOps discussions and pull request comments, gating every structural change behind user approval. ## WORKFLOW PHASES ### Phase 1 | Gather Repository...
/architectActivates Architect Mode to design software systems: analyzes trade-offs, creates docs/ADRs/diagrams, and plans implementation before coding.
/architectActivates Architect Mode to design software systems: analyzes trade-offs, creates docs/ADRs/diagrams, and plans implementation before coding.
/architectGenerates an architecture document for a system or feature based on requirements, including overview, components, data flow, tech choices with rationale, and risks.
/architectProvides system design, architecture definition, review, and technical decision oversight for the specified request.
/architectAnalyzes a question, plan, or decision from pragmatist, architect, and skeptic perspectives, then synthesizes a unified recommendation highlighting agreements and conflicts.
/architectGenerates structured PLAN.md for task in active project (requires JERRY_PROJECT env), analyzing problem, state, alternatives, steps, risks, criteria; displays for approval before proceeding.
Orchestrate architectural documentation and work-item hierarchy creation for a selected work item using Specification Driven Design (SDD). All documentation is committed to a documentation-only branch with pull request review gates at every phase. Decomposes requirements through BDD analysis, architectural design, and agile planning into a parallelizable hierarchy of work items. Enables human and agent collaboration through Azure DevOps discussions and pull request comments, gating every structural change behind user approval.
workspace is provided, split by ; and inspect each local path using the Read tool for source code, configs, and existing docsdoc is provided, split by ; and for each path call /capability:document:read --file <path> to inject local document contexturl is provided, split by ; and for each URL call /behavior:websearch --query "<url>" to fetch and inject URL contextdescription is provided, include as additional architectural contextIf selected-branch is provided AND selected-repo is provided:
/behavior:workspace:repo --action new --repo <selected-repo> --branch <selected-branch> --source-branch <target-branch|main> to create the branch/behavior:devops:pull-request --action create --portal azure --project <project> --repo <selected-repo> --source-branch <selected-branch> --target-branch <target-branch|main> --draft --title "Architecture: <feature-description>" to create the PRIf only selected-repo is provided (no selected-branch):
plan/<feature-description> from description or work item title/behavior:workspace:repo --action new --repo <selected-repo> --branch plan/<feature-description> --source-branch <target-branch|main> to create the branch/behavior:devops:pull-request --action create --portal azure --project <project> --repo <selected-repo> --source-branch plan/<feature-description> --target-branch <target-branch|main> --draft --title "Architecture: <feature-description>" to create the PRIf neither selected-repo nor selected-branch is provided:
/behavior:workspace:ask-user-question --question "Provide the repository name (--selected-repo) and optionally a branch name (--selected-branch) for documentation storage" --options "Type repo and branch below"If selected-work-item is provided:
/behavior:devops:work-item --action read --id <selected-work-item> --project <project> to retrieve Title, Description, Discussions, linked work items/behavior:devops:work-item --action link --id <selected-work-item> --project <project> --type "artifact" --link <branch-reference> to link documentation branch/behavior:devops:work-item --action link --id <selected-work-item> --project <project> --type "artifact" --link <pr-url> to link pull requestIf selected-work-item is NOT provided:
/behavior:devops:work-item --action create --project <project> --type Epic --title "<feature-description>" --description "<description-context-with-branch-and-pr-reference>" --status New to create a new Epic with start date, selected branch reference, and PR linkselected-work-item/behavior:devops:work-item --action link --id <selected-work-item> --project <project> --type "artifact" --link <branch-reference> to link documentation branch/behavior:devops:work-item --action link --id <selected-work-item> --project <project> --type "artifact" --link <pr-url> to link pull requestselected-work-item for all subsequent phases/behavior:management:clarify --context "<all-gathered-context>" to generate critical clarification questions/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post all clarification questions as a numbered list in discussion/behavior:workspace:ask-user-question --question "How would you like to provide answers to the clarification questions?" --options "a) Choose best answers automatically; b) Check selected work-item discussion for answers; c) Provide all answers in the prompt; d) Other"/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post all answers in discussion/behavior:devops:work-item --action read-discussion --id <selected-work-item> --project <project> to read all answers/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post that Phase 4 Clarification is finished/behavior:management:business --context "<all-gathered-context-with-clarification-answers>" to generate business-level behavior flows and scenarios/capability:document:write --template bdd-scenarios --title "<feature-description> User BDD Scenarios" --context "<business-bdd-output>" --output docs/user-bdd-scenarios.md to format and write user BDD document/behavior:management:architect --context "<all-gathered-context-with-clarification-answers>" to generate holistic architectural design/capability:document:write --template bdd-scenarios --title "<feature-description> Application BDD Specifications" --context "<architect-output>" --output docs/application-bdd-specifications.md to format architect output as application-level BDD specifications/behavior:development:git --action commit-push --repository <selected-repo> --branch <selected-branch> --message "docs: add behavior documentation (user and application BDD) for <feature-description>"/behavior:workspace:ask-user-question --question "Review the user BDD and application BDD documents in the pull request. How would you like to proceed?" --options "a) Continue; b) Make changes from pull-request comments; c) Make changes from prompt; d) Other"/behavior:workspace:ask-user-question --question "Review the updated behavior documents. How would you like to proceed?" --options "a) Continue; b) Make changes from pull-request comments; c) Make changes from prompt; d) Other"/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post the behavior documentation as final and that Phase 5 is finished/behavior:management:architect --context "<all-context-with-bdd-and-clarification>" to generate the complete system architecture/capability:document:write --template architecture-overview --title "<feature-description> Architecture" --context "<sdd-output>" --output docs/architecture-overview.md to write the overall architecture document/behavior:development:git --action commit-push --repository <selected-repo> --branch <selected-branch> --message "docs: add architecture overview for <feature-description>"/behavior:workspace:ask-user-question --question "Review the SDD document in the pull request. How would you like to proceed?" --options "a) Continue; b) Make changes from pull-request comments; c) Make changes from prompt; d) Other"/behavior:workspace:ask-user-question --question "Review the updated SDD document. How would you like to proceed?" --options "a) Continue; b) Make changes from pull-request comments; c) Make changes from prompt; d) Other"/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post the SDD as final and that Phase 6 is finished/behavior:management:plan --work-description "<bdd-and-sdd-combined-context>" to decompose into a parallelizable agile hierarchy taking into account BDD and SDD/capability:document:write --template implementation-plan --title "<feature-description> Implementation Plan" --context "<plan-output>" --output docs/implementation-plan.md to write the plan document/behavior:development:git --action commit-push --repository <selected-repo> --branch <selected-branch> --message "docs: add implementation plan for <feature-description>"/behavior:workspace:ask-user-question --question "Review the PLAN document in the pull request. How would you like to proceed?" --options "a) Continue; b) Make changes from pull-request comments; c) Make changes from prompt; d) Other"/behavior:workspace:ask-user-question --question "Review the updated PLAN document. How would you like to proceed?" --options "a) Continue; b) Make changes from pull-request comments; c) Make changes from prompt; d) Other"/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post the PLAN as final and that Phase 7 is finishedHierarchy reminder: Level 4 (Specific BDD scoped to services/features/user stories) and Level 5 (Specific SDD scoped to services/features/user stories) are generated here, following the overview-level designs from Phases 5 & 6.
docs/<feature-id>/<user-story-id>/<task-id>/ for task-level, docs/<feature-id>/<user-story-id>/ for user-story-level, docs/<feature-id>/ for feature-level/capability:document:write --template bdd-scenarios --title "<work-item-title> Specific BDD" --context "<work-item-context-extracted-from-overview>" --output docs/<hierarchy-path>/bdd-specifications.md — behavior scenarios this work item must implement/capability:document:write --template service-architecture --title "<work-item-title> Specific SDD" --context "<work-item-architecture-extracted-from-overview>" --output docs/<hierarchy-path>/service-architecture.md — architecture and design details for this work item/capability:document:write --template service-data-model --title "<work-item-title> Data Model" --context "<data-ownership-and-consistency-for-this-work-item>" --output docs/<hierarchy-path>/data-model.md when data modeling applies/capability:document:write --template event-notification --title "<work-item-title> Domain Events" --context "<event-catalog-for-this-work-item>" --output docs/<hierarchy-path>/domain-events.md when event-driven patterns apply/behavior:development:git --action commit-push --repository <selected-repo> --branch <selected-branch> --message "docs: add work item specifications (specific BDD and SDD) for <feature-description>"/behavior:workspace:ask-user-question --question "Review all per-work-item specifications (specific BDD and specific SDD) in the pull request. How would you like to proceed?" --options "a) Continue; b) Make changes from pull-request comments; c) Make changes from prompt; d) Other"/behavior:workspace:ask-user-question --question "Review the updated per-work-item specifications. How would you like to proceed?" --options "a) Continue; b) Make changes from pull-request comments; c) Make changes from prompt; d) Other"/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post that all per-work-item specifications (Level 4 & 5 of hierarchy) are ready and Phase 8 is finisheddocs/<feature-id>/<story-id>/<task-id>//behavior:devops:work-item --action create --project <project> --type <type> --title "<work-item-title>" --description "<markdown-formatted-description>" --status New --parent <parent-work-item-id> with start date and links/behavior:devops:work-item --action link --id <new-work-item-id> --project <project> --type "predecessor" --link-id <predecessor-work-item-id> for each predecessor dependency/behavior:devops:work-item --action link --id <new-work-item-id> --project <project> --type "successor" --link-id <successor-work-item-id> for each successor dependency/behavior:devops:work-item --action link --id <new-work-item-id> --project <project> --type "related" --link-id <related-work-item-id> for cross-linked work itemsfeature/<work-item-identifier>/<task-name>/behavior:devops:work-item --action tag --id <new-work-item-id> --project <project> --tag "wave-<wave-number>" to add wave assignment tag/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post complete work-item hierarchy with all IDs, dependencies, wave assignments, and documentation folder references/behavior:workspace:ask-user-question --question "Review all created work items in Azure DevOps. How would you like to proceed?" --options "a) Continue; b) Make changes from selected work-item discussion; c) Make changes from prompt; d) Other"/behavior:devops:work-item --action update --id <selected-work-item> --project <project> --state Active to set the selected work item to Active/behavior:devops:work-item --action post-discussion --id <selected-work-item> --project <project> to post that the selected work item is ready to be implemented and Phase 9 is finishedsequenceDiagram
participant U as User
participant C as Command
participant WM as DevOps Specialist
participant AR as Architect
participant DW as Document
participant G as Git
U->>C: /workflow:remote:architect --project P [--selected-work-item ID] [--selected-repo R] ...
Note over C: Phase 1 — Gather Context
C->>C: Read workspace, doc, url if provided
Note over C: Phase 2 — Create Branch & PR
C->>WM: /behavior:workspace:repo --action new --repo <repo> --branch <branch>
C->>WM: /behavior:devops:pull-request --action create --draft --title "Architecture: ..."
Note over C: Phase 3 — Read/Create Work Item
alt selected-work-item
C->>WM: /behavior:devops:work-item --action read --id <id>
else
C->>WM: /behavior:devops:work-item --action create --type Epic
end
C->>WM: /behavior:devops:work-item --action link --type artifact --link <branch>
C->>WM: /behavior:devops:work-item --action link --type artifact --link <pr-url>
Note over C: Phase 4 — Clarification
C->>AR: /behavior:management:clarify --context <context>
C->>WM: Post clarification questions & answers in discussion
C->>U: Confirm before proceeding
Note over C: Phase 5 — Level 1 & 2 (User/Business BDD + Application BDD)
C->>AR: /behavior:management:business → user scenarios, outcomes
C->>DW: Format business → user BDD scenarios
C->>AR: /behavior:management:architect → application interactions
C->>DW: Format architect → application BDD specifications
C->>G: Commit & push
C->>U: Review & approve in PR
Note over C: Phase 6 — Level 3 (SDD Overview)
C->>AR: /behavior:management:architect → system architecture
C->>DW: Write architecture overview
C->>G: Commit & push
C->>U: Review & approve in PR
Note over C: Phase 7 — Implementation Plan
C->>AR: /behavior:management:plan → agile hierarchy
C->>DW: Write implementation plan
C->>G: Commit & push
C->>U: Review & approve in PR
Note over C: Phase 8 — Level 4 & 5 (Specific BDD + SDD)
loop For each work item
C->>DW: Extract & write Specific BDD & SDD from overview
end
C->>G: Commit & push all docs
C->>U: Review & approve in PR
Note over C: Phase 9 — Create Work Items
loop For each work item
C->>WM: /behavior:devops:work-item --action create --description <markdown>
C->>WM: /behavior:devops:work-item --action link --type predecessor/successor/related
C->>WM: /behavior:devops:work-item --action tag --tag wave-<N>
C->>WM: Post BDD/SDD in discussion (if applicable)
end
C->>WM: Post work-item hierarchy summary in discussion
C->>U: Review work items & approve
C->>WM: /behavior:devops:work-item --action update --id <epic> --state Active
C-->>U: Complete — architecture & work items ready
Hierarchy of Thinking Validation:
Execution Gates:
workspace:repo --action new with draft pull request before any commitsArchitecture Quality Standards (applied at all levels):
Documentation Completeness:
Work Item Creation:
Integrity:
/workflow:remote:architect --project MyProject --selected-work-item 2001 --selected-repo my-docs --selected-branch plan/notification-service --target-branch main --description "Multi-tenant notification service with email, SMS, and push channels"
/workflow:remote:architect --project MyProject --selected-repo my-docs --doc "./docs/requirements.pdf;./docs/wireframes.png" --workspace "./workspace/payments.worktrees/master;./workspace/gateway.worktrees/master"
/workflow:remote:architect --project MyProject --selected-work-item 1850 --selected-repo architecture-docs --description "Refactor payment gateway" --url "https://docs.stripe.com/api;https://docs.adyen.com/api" --workspace ./workspace/payments.worktrees/master