From 2339ef1a928518eba082fa4c44db6cab4a00c064 Mon Sep 17 00:00:00 2001 From: chickymonkeys Date: Tue, 21 Oct 2025 11:52:19 +0200 Subject: [PATCH 1/4] feat: initialize `architecture` command for project scaffolding --- command/architecture.md | 217 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 command/architecture.md diff --git a/command/architecture.md b/command/architecture.md new file mode 100644 index 00000000..2cf887d7 --- /dev/null +++ b/command/architecture.md @@ -0,0 +1,217 @@ +--- +description: Initialize architecture documentation for a new project. Creates foundational design documents in thoughts/architecture/ directory. +--- + +# Initialize Architecture Documentation + +You are creating the foundational architecture documentation structure for a project. These documents guide both human developers and AI agents throughout the development lifecycle by serving as the single source of truth for design decisions, technical constraints, and system behavior. + +## Steps to follow: + +### 1. Check for existing architecture + +Check if `thoughts/architecture/` directory exists and contains files. + +If files exist: +- List existing files to the user +- Ask: "Architecture documentation already exists. Would you like to (1) Skip and keep existing, (2) Add missing files only, or (3) Regenerate all files?" +- Proceed based on user choice + +If directory doesn't exist, proceed to create it. + +### 2. Gather project context + +Ask focused questions to understand the project: + +1. What is this project? (Brief description of purpose and scope) +2. What is the primary tech stack? (Languages, frameworks, key libraries) +3. Does this project have: APIs, CLI, event-driven components, or other interfaces? + +Keep questions minimal and focused. Use responses to determine which documents to create. + +### 3. Create architecture directory structure + +Create `thoughts/architecture/` directory if it doesn't exist. + +### 4. Generate core architecture documents + +Create these **required** documents with appropriate placeholder content: + +**thoughts/architecture/overview.md** - High-level navigation guide +- Synopsis of each architecture document +- How documents relate to each other +- Quick reference for project structure + +**thoughts/architecture/system-architecture.md** - Technical infrastructure +- Programming languages and usage patterns +- Frameworks, libraries, dependencies +- Infrastructure components (databases, caches, queues, etc.) +- Build and deployment tooling +- Development environment requirements +- Configuration management + +**thoughts/architecture/domain-model.md** - Business logic and features +- Core domain concepts and entities +- Business rules and constraints +- Key workflows and processes +- Data relationships +- Domain terminology + +**thoughts/architecture/testing-strategy.md** - Testing approach +- Unit testing conventions and tools +- Integration testing patterns +- End-to-end testing approach +- Test data management +- Quality gates and coverage targets + +**thoughts/architecture/development-workflow.md** - Development process +- Ticket workflow (research → plan → execute → review) +- Code review standards +- Branching strategy +- CI/CD pipeline +- Documentation maintenance + +**thoughts/architecture/persistence.md** - Data storage +- Storage technologies and versions +- Schema design principles +- Migration strategy +- Caching approach +- Backup and recovery procedures + +### 5. Generate optional documents based on context + +Based on user's responses in step 2, create applicable optional documents: + +**thoughts/architecture/api-design.md** (if project has APIs) +- Endpoint design patterns +- Authentication and authorization +- Versioning strategy +- Request/response formats +- Error handling conventions + +**thoughts/architecture/cli-design.md** (if project has CLI) +- Command structure +- Configuration approach +- Output formatting +- Error handling + +**thoughts/architecture/event-bus.md** (if project uses events) +- Event types and schemas +- Publishing and subscription patterns +- Error handling and retries + +### 6. Populate documents with project-specific content + +For each document created: + +1. Use a consistent template structure: +```markdown +# [Document Title] + +> This document describes [specific purpose]. Last updated: [date] + +## Overview + +[Brief description of this document's role in the architecture] + +## [Section 1] + +[Content based on user's project context] + +## [Section 2] + +[Content based on user's project context] + +## TODO + +- [ ] [Specific decision or detail needed] +- [ ] [Another item requiring future clarification] + +## Related Documentation + +- [Link to related architecture document] +``` + +2. Use placeholder text that prompts users to fill in specifics: + - "Describe the primary programming language and version" + - "List key frameworks and explain their usage" + - "Document database choice and rationale" + +3. Include concrete examples only where universally applicable +4. Add TODO sections for project-specific decisions +5. Cross-reference related documents + +### 7. Present completion summary + +Show user what was created: + +```markdown +Architecture documentation initialized in thoughts/architecture/ + +Core documents created: + ✓ overview.md - Architecture navigation guide + ✓ system-architecture.md - Technical infrastructure + ✓ domain-model.md - Business logic and features + ✓ testing-strategy.md - Testing approach + ✓ development-workflow.md - Development process + ✓ persistence.md - Data storage design + +Optional documents created: + ✓ api-design.md (if applicable) + ✓ cli-design.md (if applicable) + ✓ event-bus.md (if applicable) + +Next steps: +1. Review each document and fill in TODO sections +2. Replace placeholder text with project-specific details +3. Update documents as architectural decisions are made +4. These docs will be referenced by /research, /plan, and /execute commands +``` + +Use the todowrite tool to create a structured task list for the 7 steps above, marking each as pending initially. + +## Important Guidelines + +### Document Content Strategy + +**Use placeholders and prompts, not examples:** +- Template text should guide users to add their own details +- Avoid technology-specific examples unless universal +- Use phrases like "Describe your approach to..." or "Document the..." +- Include TODO checklists for items requiring decisions + +**Be architecture-agnostic:** +- Don't assume web apps, APIs, or specific patterns +- Adapt document generation to project type +- Create only relevant optional documents +- Scale complexity to project size + +**Focus on guidance:** +- Each document should teach what to document +- Explain why each section matters +- Provide structure without dictating content +- Enable users to make informed decisions + +### File Management + +- Use Write tool to create new files +- Use List tool to check existing files +- Never overwrite without explicit user confirmation +- Preserve any existing user content + +### User Interaction + +- Keep initial questions minimal (3-4 max) +- Confirm before creating/overwriting files +- Present clear summaries of actions taken +- Be ready to iterate if user requests changes + +### Integration with Workflow + +These documents are referenced by: +- `/research` - Discovers architectural constraints +- `/plan` - Uses architecture as implementation guide +- `/execute` - Follows architectural patterns +- `/review` - Validates alignment with architecture + +$ARGUMENTS \ No newline at end of file From e0a32a870b8a3d58eb1d6205010012090e4a83f7 Mon Sep 17 00:00:00 2001 From: chickymonkeys Date: Tue, 21 Oct 2025 12:10:58 +0200 Subject: [PATCH 2/4] feat(architecture-command): handle refining mode and create mode for architecture steering docs --- command/architecture.md | 175 +++++++++++++++++++++++++++++++++------- 1 file changed, 146 insertions(+), 29 deletions(-) diff --git a/command/architecture.md b/command/architecture.md index 2cf887d7..f2a59a14 100644 --- a/command/architecture.md +++ b/command/architecture.md @@ -8,32 +8,112 @@ You are creating the foundational architecture documentation structure for a pro ## Steps to follow: -### 1. Check for existing architecture +### 1. Determine execution mode Check if `thoughts/architecture/` directory exists and contains files. -If files exist: +**PATH A - If architecture files exist (REFINE MODE):** - List existing files to the user -- Ask: "Architecture documentation already exists. Would you like to (1) Skip and keep existing, (2) Add missing files only, or (3) Regenerate all files?" -- Proceed based on user choice +- Inform: "Architecture documentation found. I can analyze the codebase and update these documents to align with current implementation." +- Ask: "Would you like to: (1) Skip refinement, (2) Refine existing documents based on codebase analysis?" +- If user chooses refinement, proceed to **Step 2A: Refine Existing Architecture** +- If user skips, exit gracefully -If directory doesn't exist, proceed to create it. +**PATH B - If no architecture files exist (CREATE MODE):** +- Inform: "No architecture documentation found. I'll help you create it." +- Proceed to **Step 2B: Gather Project Context** -### 2. Gather project context +--- + +### 2A. Refine Existing Architecture (PATH A only) + +**Phase 1 - Locate (Codebase & Architecture):** +- Spawn **codebase-locator** agents in parallel to discover: + - Main application entry points + - Key module and component locations + - Infrastructure configuration files + - Testing setup and conventions +- Spawn **thoughts-locator** agent to analyze existing architecture documents +- **WAIT** for all locator agents to complete + +**Phase 2 - Find Patterns (Codebase only):** +- Based on locator results, spawn **codebase-pattern-finder** agents in parallel to identify: + - Architectural patterns in use + - Testing patterns and conventions + - API/CLI design patterns (if applicable) + - Data persistence patterns +- **WAIT** for all pattern-finder agents to complete + +**Phase 3 - Analyze (Codebase & Architecture):** +- Spawn **codebase-analyzer** agents in parallel to understand: + - Current system architecture and stack + - Domain model implementation + - Development workflow artifacts + - Persistence layer details +- Spawn **thoughts-analyzer** agent to extract key insights from existing architecture docs +- **WAIT** for all analyzer agents to complete + +**Synthesize and Update:** +- Compare codebase reality with existing architecture documentation +- Identify discrepancies, outdated information, and missing details +- Present findings to user with specific update recommendations +- Ask: "I found [N] areas where documentation differs from implementation. Update all, select specific documents, or cancel?" +- Update selected documents with current codebase information +- Preserve user-added content and TODOs where applicable +- Add update timestamp and changelog notes to modified documents +- Skip to **Step 7: Present Completion Summary** + +--- + +### 2B. Gather Project Context (PATH B only) + +**Broad Discovery Phase:** + +Ask minimal high-level questions first: + +1. What is this project's primary purpose and domain? (e.g., "API for managing e-commerce orders", "CLI tool for data analysis") +2. What technology stack is in use? (Languages, frameworks, key libraries) + +**Determine Document Scope:** + +Based on responses, determine which architectural documents are necessary: +- Core documents (always created): overview, system-architecture, domain-model, testing-strategy, development-workflow, persistence +- Optional documents (conditionally created): + - `api-design.md` if project has REST/GraphQL APIs + - `cli-design.md` if project has CLI interface + - `event-bus.md` if project uses event-driven architecture + +**Focused Follow-up Phase:** -Ask focused questions to understand the project: +For each document to be created, ask targeted questions: -1. What is this project? (Brief description of purpose and scope) -2. What is the primary tech stack? (Languages, frameworks, key libraries) -3. Does this project have: APIs, CLI, event-driven components, or other interfaces? +For `system-architecture.md`: +- What versions of key technologies are in use? +- Are there specific infrastructure dependencies (databases, caches, message queues)? +- What build/deployment tooling is configured? -Keep questions minimal and focused. Use responses to determine which documents to create. +For `domain-model.md`: +- What are the core business entities? +- Are there critical business rules or constraints? +- What are the main user workflows? -### 3. Create architecture directory structure +For `persistence.md`: +- What data storage technologies are in use? +- Is there a migration strategy in place? +- Are there caching or performance considerations? -Create `thoughts/architecture/` directory if it doesn't exist. +For optional documents (only if applicable): +- API: Authentication approach? Versioning strategy? Error handling patterns? +- CLI: Command structure? Configuration approach? Output formats? +- Events: Event types? Publishing patterns? Error handling? -### 4. Generate core architecture documents +Keep follow-up questions focused and skip those where answers are obvious from earlier responses. + +### 3. Create architecture directory structure (PATH B only) + +Create `thoughts/architecture/` directory. + +### 4. Generate core architecture documents (PATH B only) Create these **required** documents with appropriate placeholder content: @@ -78,9 +158,9 @@ Create these **required** documents with appropriate placeholder content: - Caching approach - Backup and recovery procedures -### 5. Generate optional documents based on context +### 5. Generate optional documents based on context (PATH B only) -Based on user's responses in step 2, create applicable optional documents: +Based on user's responses in step 2B, create applicable optional documents: **thoughts/architecture/api-design.md** (if project has APIs) - Endpoint design patterns @@ -100,7 +180,7 @@ Based on user's responses in step 2, create applicable optional documents: - Publishing and subscription patterns - Error handling and retries -### 6. Populate documents with project-specific content +### 6. Populate documents with project-specific content (PATH B only) For each document created: @@ -116,11 +196,11 @@ For each document created: ## [Section 1] -[Content based on user's project context] +[Content based on user's project context from step 2B] ## [Section 2] -[Content based on user's project context] +[Content based on user's project context from step 2B] ## TODO @@ -132,19 +212,39 @@ For each document created: - [Link to related architecture document] ``` -2. Use placeholder text that prompts users to fill in specifics: - - "Describe the primary programming language and version" - - "List key frameworks and explain their usage" - - "Document database choice and rationale" +2. Use responses from step 2B to populate content: + - Incorporate technology stack details + - Document infrastructure dependencies mentioned + - Include business entities and workflows described + - Reflect build/deployment tooling discussed -3. Include concrete examples only where universally applicable -4. Add TODO sections for project-specific decisions +3. Use placeholder text only for areas not covered in interview: + - "Describe [specific aspect not yet discussed]" + - "Document [decision to be made later]" + +4. Add TODO sections for project-specific decisions still needed 5. Cross-reference related documents ### 7. Present completion summary -Show user what was created: +**For PATH A (Refine Mode):** +```markdown +Architecture documentation updated in thoughts/architecture/ + +Documents refined: + ✓ [list of updated documents with brief change summary] +Changes made: + - [summary of key updates] + - [alignment improvements] + +Next steps: +1. Review updated content for accuracy +2. Address any new TODO items added +3. Continue iterating as implementation evolves +``` + +**For PATH B (Create Mode):** ```markdown Architecture documentation initialized in thoughts/architecture/ @@ -163,12 +263,12 @@ Optional documents created: Next steps: 1. Review each document and fill in TODO sections -2. Replace placeholder text with project-specific details +2. Refine details as implementation progresses 3. Update documents as architectural decisions are made 4. These docs will be referenced by /research, /plan, and /execute commands ``` -Use the todowrite tool to create a structured task list for the 7 steps above, marking each as pending initially. +Use the todowrite tool to create a structured task list, marking each as pending initially. Task list will vary based on execution path. ## Important Guidelines @@ -201,11 +301,28 @@ Use the todowrite tool to create a structured task list for the 7 steps above, m ### User Interaction -- Keep initial questions minimal (3-4 max) +- **PATH A (Refine):** Present findings and ask for confirmation before updating +- **PATH B (Create):** Keep initial questions minimal (2 broad questions), follow with focused questions - Confirm before creating/overwriting files - Present clear summaries of actions taken - Be ready to iterate if user requests changes +### Execution Path Requirements + +**PATH A - Refine Mode Requirements:** +- Must use sub-agents in three phases: Locate → Find Patterns → Analyze +- Must spawn agents in parallel within each phase (never mix agent types across phases) +- Must compare codebase reality to documentation before proposing updates +- Must preserve user content and maintain document structure +- Must add timestamps and change notes to updated documents + +**PATH B - Create Mode Requirements:** +- Must start with broad questions before determining document scope +- Must ask focused follow-up questions only for selected documents +- Must populate documents with user-provided information from interviews +- Must use placeholders only for information not gathered in interview +- Must create only core + applicable optional documents based on project type + ### Integration with Workflow These documents are referenced by: From 60a4434a5edc3fd3c8a49362e6ec52162c2d457c Mon Sep 17 00:00:00 2001 From: chickymonkeys Date: Tue, 21 Oct 2025 13:48:06 +0200 Subject: [PATCH 3/4] feat(architecture-command): refine `architecture` command declaration --- command/architecture.md | 99 +++++++++++++---------------------------- 1 file changed, 30 insertions(+), 69 deletions(-) diff --git a/command/architecture.md b/command/architecture.md index f2a59a14..deb1d899 100644 --- a/command/architecture.md +++ b/command/architecture.md @@ -1,10 +1,10 @@ --- -description: Initialize architecture documentation for a new project. Creates foundational design documents in thoughts/architecture/ directory. +description: Initialize or refine architecture documentation for a new project. Creates or updates foundational design documents in thoughts/architecture/ directory. --- -# Initialize Architecture Documentation +# Architecture Documentation -You are creating the foundational architecture documentation structure for a project. These documents guide both human developers and AI agents throughout the development lifecycle by serving as the single source of truth for design decisions, technical constraints, and system behavior. +You are creating or refining the foundational architecture documentation structure for a project. These documents guide both human developers and AI agents throughout the development lifecycle by serving as the single source of truth for design decisions, technical constraints, and system behavior. ## Steps to follow: @@ -113,9 +113,9 @@ Keep follow-up questions focused and skip those where answers are obvious from e Create `thoughts/architecture/` directory. -### 4. Generate core architecture documents (PATH B only) +### 4. Generate architecture documents (PATH B only) -Create these **required** documents with appropriate placeholder content: +Create **core documents** (always required): **thoughts/architecture/overview.md** - High-level navigation guide - Synopsis of each architecture document @@ -137,7 +137,7 @@ Create these **required** documents with appropriate placeholder content: - Data relationships - Domain terminology -**thoughts/architecture/testing-strategy.md** - Testing approach +**thoughts/architecture/testing-strategy.md**- Testing approach - Unit testing conventions and tools - Integration testing patterns - End-to-end testing approach @@ -150,48 +150,29 @@ Create these **required** documents with appropriate placeholder content: - Branching strategy - CI/CD pipeline - Documentation maintenance - -**thoughts/architecture/persistence.md** - Data storage +comunque a +**thoughts/architecture/persistence.md**- Data storage - Storage technologies and versions - Schema design principles - Migration strategy - Caching approach - Backup and recovery procedures -### 5. Generate optional documents based on context (PATH B only) - -Based on user's responses in step 2B, create applicable optional documents: - -**thoughts/architecture/api-design.md** (if project has APIs) -- Endpoint design patterns -- Authentication and authorization -- Versioning strategy -- Request/response formats -- Error handling conventions - -**thoughts/architecture/cli-design.md** (if project has CLI) -- Command structure -- Configuration approach -- Output formatting -- Error handling - -**thoughts/architecture/event-bus.md** (if project uses events) -- Event types and schemas -- Publishing and subscription patterns -- Error handling and retries +Create **optional documents** based on context from step 2B, for example: -### 6. Populate documents with project-specific content (PATH B only) +- **thoughts/architecture/api-design.md** (if project has APIs) - Endpoints, auth, versioning, request/response formats, error handling +- **thoughts/architecture/cli-design.md** (if project has CLI) - Commands, configuration, output formatting, error handling +- **thoughts/architecture/event-bus.md** (if project uses events) - Event types/schemas, pub/sub patterns, error handling -For each document created: +### 5. Populate documents with project-specific content (PATH B only) -1. Use a consistent template structure: +Use this consistent template structure: ```markdown # [Document Title] > This document describes [specific purpose]. Last updated: [date] ## Overview - [Brief description of this document's role in the architecture] ## [Section 1] @@ -202,38 +183,27 @@ For each document created: [Content based on user's project context from step 2B] +[... Additional Sections as Needed ...] + ## TODO - [ ] [Specific decision or detail needed] - [ ] [Another item requiring future clarification] ## Related Documentation - -- [Link to related architecture document] +- [Links to related architecture documents] ``` -2. Use responses from step 2B to populate content: - - Incorporate technology stack details - - Document infrastructure dependencies mentioned - - Include business entities and workflows described - - Reflect build/deployment tooling discussed - -3. Use placeholder text only for areas not covered in interview: - - "Describe [specific aspect not yet discussed]" - - "Document [decision to be made later]" +Populate with user's responses from step 2B. Use placeholder text only for uncovered areas ("Describe [specific aspect not yet discussed]", "Document [decision to be made later]"). Cross-reference related documents. -4. Add TODO sections for project-specific decisions still needed -5. Cross-reference related documents +### 6. Present completion summary -### 7. Present completion summary - -**For PATH A (Refine Mode):** +**PATH A (Refine Mode):** ```markdown Architecture documentation updated in thoughts/architecture/ Documents refined: ✓ [list of updated documents with brief change summary] - Changes made: - [summary of key updates] - [alignment improvements] @@ -244,7 +214,7 @@ Next steps: 3. Continue iterating as implementation evolves ``` -**For PATH B (Create Mode):** +**PATH B (Create Mode):** ```markdown Architecture documentation initialized in thoughts/architecture/ @@ -255,11 +225,7 @@ Core documents created: ✓ testing-strategy.md - Testing approach ✓ development-workflow.md - Development process ✓ persistence.md - Data storage design - -Optional documents created: - ✓ api-design.md (if applicable) - ✓ cli-design.md (if applicable) - ✓ event-bus.md (if applicable) +Optional documents (if applicable): ✓ [e.g. api-design.md / cli-design.md / event-bus.md] Next steps: 1. Review each document and fill in TODO sections @@ -279,46 +245,41 @@ Use the todowrite tool to create a structured task list, marking each as pending - Avoid technology-specific examples unless universal - Use phrases like "Describe your approach to..." or "Document the..." - Include TODO checklists for items requiring decisions - **Be architecture-agnostic:** - Don't assume web apps, APIs, or specific patterns - Adapt document generation to project type - Create only relevant optional documents - Scale complexity to project size - **Focus on guidance:** - Each document should teach what to document - Explain why each section matters - Provide structure without dictating content - Enable users to make informed decisions +- Include TODO checklists for decisions ### File Management - - Use Write tool to create new files - Use List tool to check existing files - Never overwrite without explicit user confirmation - Preserve any existing user content ### User Interaction - -- **PATH A (Refine):** Present findings and ask for confirmation before updating -- **PATH B (Create):** Keep initial questions minimal (2 broad questions), follow with focused questions +- **PATH A:** Present findings, ask confirmation before updating +- **PATH B:** Start with 2 broad questions, follow with focused questions only for selected documents - Confirm before creating/overwriting files - Present clear summaries of actions taken -- Be ready to iterate if user requests changes ### Execution Path Requirements - -**PATH A - Refine Mode Requirements:** +**PATH A - Refine Mode:** - Must use sub-agents in three phases: Locate → Find Patterns → Analyze - Must spawn agents in parallel within each phase (never mix agent types across phases) -- Must compare codebase reality to documentation before proposing updates +- Must compare codebase to docs before proposing updates - Must preserve user content and maintain document structure - Must add timestamps and change notes to updated documents -**PATH B - Create Mode Requirements:** -- Must start with broad questions before determining document scope -- Must ask focused follow-up questions only for selected documents +**PATH B - Create Mode:** +- Must start with broad questions before determining scope +- Must ask focused follow-ups only for selected documents - Must populate documents with user-provided information from interviews - Must use placeholders only for information not gathered in interview - Must create only core + applicable optional documents based on project type From fe74dd6e002604129df266c66b196dc2a8984a3a Mon Sep 17 00:00:00 2001 From: chickymonkeys Date: Tue, 21 Oct 2025 15:51:54 +0200 Subject: [PATCH 4/4] docs(architecture-command): :memo: update documentation to fit `architecture` command --- README.md | 17 +++++++++-------- docs/commands.md | 21 +++++++++++++++++++++ docs/workflow.md | 24 +++++++++++++++++++++++- 3 files changed, 53 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 551826a4..a9451bd0 100644 --- a/README.md +++ b/README.md @@ -64,17 +64,18 @@ agentic pull ### Development Workflow -1. Use the **ticket** command to work with the agent to build out ticket details -2. Use the **research** command to analyze the codebase from the ticket details -3. Use the **plan** command to generate an implementation plan for the ticket using the research -4. Use the **execute** command to implement the changes -5. Use the **commit** command to commit your work -6. Use the **review** command to verify the implementation +1. **(Optional)** Use the **architecture** command to establish or refine foundational architecture documentation +2. Use the **ticket** command to work with the agent to build out ticket details +3. Use the **research** command to analyze the codebase from the ticket details +4. Use the **plan** command to generate an implementation plan for the ticket using the research +5. Use the **execute** command to implement the changes +6. Use the **commit** command to commit your work +7. Use the **review** command to verify the implementation Between each phase it is important to inspect the output from each phase and ensure that it is actually in alignment with what you want the project do be and the direction it is going. Errors in these files will cascade to the next phase and produce code that is not what you wanted. -In OpenCode, these commands are invoked with a slash: `/ticket`, `/research`, `/plan`, `/execute`, etc. -Most of these commands want the ticket in question that you want to review, exceptions are ticket itself, and commit/review. Ticket you give an actual prompt that describes what you're trying to do, and commit/review are meant to work in the context window that you ran execute in so that it has all of the details of how the process itself went. +In OpenCode, these commands are invoked with a slash: `/architecture`, `/ticket`, `/research`, `/plan`, `/execute`, etc. +Most of these commands want the ticket in question that you want to review, exceptions are architecture, ticket itself, and commit/review. Architecture guides you through creating or refining foundational docs. Ticket you give an actual prompt that describes what you're trying to do, and commit/review are meant to work in the context window that you ran execute in so that it has all of the details of how the process itself went. ## Documentation diff --git a/docs/commands.md b/docs/commands.md index 5d530ba0..f95e6a73 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -19,6 +19,27 @@ Example: ## Available Commands +### architecture command (`/architecture`) + +**Purpose**: Initialize or refine architecture documentation for a project. + +**Syntax**: `/architecture` + +**Example**: +``` +/architecture +``` + +**Process**: +1. Checks if thoughts/architecture/ exists and contains files +2. If exists: Offers to refine docs based on codebase analysis +3. If not: Guides user through creating foundational docs +4. Spawns specialized agents for codebase/documentation analysis +5. Creates core documents (overview, system-architecture, domain-model, testing-strategy, development-workflow, persistence) +6. Optionally creates specialized docs (api-design, cli-design, event-bus) + +**Output**: `thoughts/architecture/*.md` files + ### research command (`/research`) **Purpose**: Comprehensive analysis of codebase and documentation. diff --git a/docs/workflow.md b/docs/workflow.md index 3ade1021..89777daa 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -6,6 +6,26 @@ The Agentic workflow provides a structured, phase-based approach to software dev ## Workflow Phases +### 0. Architecture Setup (Optional) + +**Purpose**: Establish foundational architecture documentation. + +**Command**: `/architecture` + +**Process**: +1. Determines if creating new or refining existing docs +2. Interviews user about project structure and decisions +3. Creates comprehensive architecture documents +4. Provides foundation for all subsequent phases + +**Output**: `thoughts/architecture/*.md` + +**Key Points**: +- Recommended for new projects or major refactors +- Can be refined as implementation evolves +- Referenced by research, plan, and execute commands +- Serves as single source of truth for design decisions + ### 1. Research Phase **Purpose**: Understand the codebase and gather context for implementation. @@ -123,6 +143,8 @@ Agents automatically compress context by: ## Decision Flow ``` +Architecture Setup (Optional) + ↓ Ticket Created ↓ Research Phase → Research Document @@ -266,4 +288,4 @@ Each phase has quality requirements: - [Usage Guide](./usage.md) - [Commands](./commands.md) - [Thoughts Directory](./thoughts.md) -- [Architecture](./architecture.md) \ No newline at end of file +- [Architecture](./architecture.md)