initial commit
This commit is contained in:
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: 'step-01-define-question'
|
||||
description: 'Articulate exactly what you need to understand about the codebase before reading a single file'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-02-scan-codebase.md'
|
||||
---
|
||||
|
||||
# Step 1: Define Question
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Articulate exactly what you need to understand about the codebase before reading a single file.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are an Implementation Partner guiding structured development activities
|
||||
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
|
||||
- ✅ Maintain clear and structured tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on defining clear analysis questions, scope, expected output, and time box
|
||||
- 🚫 FORBIDDEN to begin scanning or reading any codebase files — that is a later step
|
||||
- 💬 Approach: Help user articulate their question clearly and set boundaries before any exploration
|
||||
- 📋 If user provides vague questions, help them sharpen and prioritize
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Produce a clear, scoped analysis question with defined boundaries
|
||||
- 💾 Save the question, scope, output format, and time box for subsequent steps
|
||||
- 📖 Reference the category table and scope options to guide user
|
||||
- 🚫 Do not open, scan, or explore any code during this step
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: User's initial request or motivation for analysis
|
||||
- Focus: Defining what to analyze and how to scope it
|
||||
- Limits: No codebase exploration yet — purely planning
|
||||
- Dependencies: None — this is the first step
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Articulate the Question
|
||||
|
||||
Write down what you need to understand. Common analysis questions:
|
||||
|
||||
| Category | Example Questions |
|
||||
|----------|-------------------|
|
||||
| **Architecture** | How is this application structured? What patterns does it use? |
|
||||
| **Dependencies** | What does this module depend on? What would break if I change it? |
|
||||
| **Patterns** | What conventions does the team follow? Where are they inconsistent? |
|
||||
| **Performance** | Where are the bottlenecks? What queries are expensive? |
|
||||
| **Data flow** | How does data move from user input to database and back? |
|
||||
| **Integration** | What external services does this connect to? How? |
|
||||
| **Security** | Where is authentication handled? Are there exposed endpoints? |
|
||||
|
||||
Write the question in plain language. If you have multiple questions, prioritize them.
|
||||
|
||||
### 2. Define Scope
|
||||
|
||||
Determine what is in and out of scope:
|
||||
|
||||
- **Entire codebase** — Full architecture review (use for onboarding or documentation)
|
||||
- **Specific module** — One feature area, service, or package
|
||||
- **Cross-cutting concern** — Authentication, error handling, logging across the codebase
|
||||
- **Integration boundary** — How two systems communicate
|
||||
|
||||
Be explicit about what you will NOT analyze. Unbounded scope leads to analysis paralysis.
|
||||
|
||||
### 3. Define Expected Output
|
||||
|
||||
Decide what the analysis should produce:
|
||||
|
||||
- **Architecture map** — High-level component diagram with relationships
|
||||
- **Dependency graph** — Module dependencies, import chains
|
||||
- **Pattern catalog** — Design patterns used, where, and how consistently
|
||||
- **API map** — Endpoints, request/response shapes, authentication
|
||||
- **Data model** — Entity relationships, storage patterns
|
||||
- **Risk assessment** — Tech debt, security concerns, fragile areas
|
||||
|
||||
### 4. Set Time Box
|
||||
|
||||
Decide how long the analysis should take. Recommended:
|
||||
|
||||
| Scope | Time Box |
|
||||
|-------|----------|
|
||||
| Single module | 15-30 min |
|
||||
| Feature area | 30-60 min |
|
||||
| Full codebase | 1-2 hours |
|
||||
|
||||
If the time box expires, document what you found and what remains unexplored.
|
||||
|
||||
### 5. Verify Checklist
|
||||
|
||||
- [ ] Question is written in plain language
|
||||
- [ ] Scope boundaries are defined (what is in, what is out)
|
||||
- [ ] Expected output format is chosen
|
||||
- [ ] Time box is set
|
||||
|
||||
### 6. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 2: Scan Codebase"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- User can chat or ask questions - always respond and then redisplay menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN the user has confirmed a clear question, scope, output format, and time box will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Question is written in plain language
|
||||
- Scope boundaries are defined (what is in, what is out)
|
||||
- Expected output format is chosen
|
||||
- Time box is set
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Beginning codebase exploration before question is defined
|
||||
- Proceeding without clear scope boundaries
|
||||
- Skipping time box definition
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,179 @@
|
||||
---
|
||||
name: 'step-02-scan-codebase'
|
||||
description: 'Build a mental model of the codebase through systematic exploration of structure, tech stack, and entry points'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-03-map-architecture.md'
|
||||
---
|
||||
|
||||
# Step 2: Scan Codebase
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Build a mental model of the codebase through systematic exploration of structure, tech stack, and entry points.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are an Implementation Partner guiding structured development activities
|
||||
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
|
||||
- ✅ Maintain clear and structured tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on scanning structure, tech stack, entry points, configuration, and build pipeline
|
||||
- 🚫 FORBIDDEN to begin deep architectural analysis — that is the next step
|
||||
- 💬 Approach: Systematically explore top-level structure and record observations with user
|
||||
- 📋 Document observations as you go — structure, stack, patterns
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Map directory structure, identify tech stack, locate entry points
|
||||
- 💾 Document structure overview, tech stack, entry points, configuration, pipeline, and initial patterns
|
||||
- 📖 Use the question and scope defined in Step 1 to guide scanning focus
|
||||
- 🚫 Do not trace data flows or map dependencies in detail yet
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Analysis question, scope, output format, and time box from Step 1
|
||||
- Focus: High-level codebase reconnaissance
|
||||
- Limits: No deep architectural mapping — stay at survey level
|
||||
- Dependencies: Step 1 must be complete (question and scope defined)
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Read Project Structure
|
||||
|
||||
Start with a directory listing of the root and first two levels:
|
||||
|
||||
- Note the top-level folders and what they suggest (e.g., `src/`, `lib/`, `tests/`, `docs/`)
|
||||
- Identify organizational patterns: by feature, by layer, by module, flat
|
||||
- Note any unusual or project-specific folders
|
||||
|
||||
Record observations:
|
||||
|
||||
```
|
||||
Root structure:
|
||||
- src/ — Application source code
|
||||
- tests/ — Test suites
|
||||
- scripts/ — Build and utility scripts
|
||||
- docs/ — Documentation
|
||||
- ...
|
||||
```
|
||||
|
||||
### 2. Identify Tech Stack and Frameworks
|
||||
|
||||
Read key configuration files:
|
||||
|
||||
| File | Reveals |
|
||||
|------|---------|
|
||||
| `package.json` / `requirements.txt` / `Cargo.toml` | Dependencies, scripts, project metadata |
|
||||
| `tsconfig.json` / `pyproject.toml` | Language configuration |
|
||||
| `.env.example` / `.env.template` | Environment variables needed |
|
||||
| `docker-compose.yml` / `Dockerfile` | Container setup, services |
|
||||
| `Makefile` / `justfile` | Build commands |
|
||||
|
||||
Document the stack:
|
||||
|
||||
```
|
||||
Tech stack:
|
||||
- Language: TypeScript 5.x
|
||||
- Framework: Next.js 14
|
||||
- Database: PostgreSQL via Prisma
|
||||
- Testing: Vitest + Playwright
|
||||
- Deployment: Docker → AWS ECS
|
||||
```
|
||||
|
||||
### 3. Map Entry Points
|
||||
|
||||
Find where execution starts:
|
||||
|
||||
- **Web app:** Main page/route, layout files, app entry
|
||||
- **API:** Server entry, route definitions, middleware chain
|
||||
- **CLI:** Main command file, argument parsing
|
||||
- **Library:** Exported modules, public API surface
|
||||
|
||||
### 4. Read Configuration Files
|
||||
|
||||
Scan for configuration that shapes behavior:
|
||||
|
||||
- Environment configuration (dev/staging/prod differences)
|
||||
- Feature flags or toggles
|
||||
- Routing configuration
|
||||
- Database connection setup
|
||||
- Third-party service configuration (auth, payments, email)
|
||||
|
||||
### 5. Identify Build and Deploy Pipeline
|
||||
|
||||
Look for:
|
||||
|
||||
- CI/CD configuration (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`)
|
||||
- Build scripts and what they produce
|
||||
- Deployment targets and process
|
||||
- Environment-specific builds
|
||||
|
||||
### 6. Note Patterns Observed
|
||||
|
||||
As you scan, note initial observations about:
|
||||
|
||||
- Code organization style (monolith, monorepo, microservices)
|
||||
- Naming conventions (files, folders, variables)
|
||||
- Test organization (co-located, separate folder, both)
|
||||
- Documentation level (thorough, sparse, outdated)
|
||||
- Apparent code quality signals (linting config, formatting config, type strictness)
|
||||
|
||||
### 7. Verify Checklist
|
||||
|
||||
- [ ] Directory structure mapped (top 2 levels)
|
||||
- [ ] Tech stack and versions identified
|
||||
- [ ] Entry points located
|
||||
- [ ] Configuration files read
|
||||
- [ ] Build/deploy pipeline identified
|
||||
- [ ] Initial patterns and conventions noted
|
||||
|
||||
### 8. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 3: Map Architecture"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- User can chat or ask questions - always respond and then redisplay menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN the codebase scan is complete and observations documented will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Directory structure mapped (top 2 levels)
|
||||
- Tech stack and versions identified
|
||||
- Entry points located
|
||||
- Configuration files read
|
||||
- Build/deploy pipeline identified
|
||||
- Initial patterns and conventions noted
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Jumping into deep architecture analysis before completing the scan
|
||||
- Skipping configuration or build pipeline investigation
|
||||
- Not documenting observations systematically
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,186 @@
|
||||
---
|
||||
name: 'step-03-map-architecture'
|
||||
description: 'Build a detailed map of components, data flow, dependencies, and patterns as the analytical core of the workflow'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-04-document-findings.md'
|
||||
---
|
||||
|
||||
# Step 3: Map Architecture
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Build a detailed map of components, data flow, dependencies, and patterns. This is the analytical core of the workflow.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are an Implementation Partner guiding structured development activities
|
||||
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
|
||||
- ✅ Maintain clear and structured tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on mapping components, tracing data flows, identifying layers, integrations, state, dependencies, and patterns
|
||||
- 🚫 FORBIDDEN to begin writing the final architecture document — that is the next step
|
||||
- 💬 Approach: Deep dive into codebase structure with user, tracing flows and mapping dependencies collaboratively
|
||||
- 📋 Use the scan observations from Step 2 as your starting point
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Create comprehensive component inventory, data flow traces, and dependency maps
|
||||
- 💾 Document component map, data flows, layers, integrations, state management, dependencies, and patterns
|
||||
- 📖 Reference scan results from Step 2 and original questions from Step 1
|
||||
- 🚫 Do not write the final document yet — focus on raw analysis
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Analysis question and scope from Step 1; scan observations from Step 2
|
||||
- Focus: Deep architectural analysis — components, flows, dependencies, patterns
|
||||
- Limits: No final document writing — raw analysis only
|
||||
- Dependencies: Steps 1 and 2 must be complete
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Map Component and Module Structure
|
||||
|
||||
For each major module or component area:
|
||||
|
||||
- What is its responsibility?
|
||||
- What does it expose (public API, exports)?
|
||||
- What does it encapsulate (internal details)?
|
||||
- How large is it (files, lines, complexity)?
|
||||
|
||||
Create a component inventory:
|
||||
|
||||
```
|
||||
Components:
|
||||
- AuthModule — Handles login, registration, session management
|
||||
- UserService — CRUD operations for user profiles
|
||||
- PaymentGateway — Stripe integration, invoice generation
|
||||
- NotificationService — Email + push notifications
|
||||
- ...
|
||||
```
|
||||
|
||||
### 2. Trace Data Flow
|
||||
|
||||
Pick 2-3 key user actions and trace data from start to finish:
|
||||
|
||||
1. **User action** (click, form submit, page load)
|
||||
2. **Frontend handling** (event handler, state update, API call)
|
||||
3. **API layer** (route, middleware, validation)
|
||||
4. **Business logic** (service, domain logic, transformations)
|
||||
5. **Data layer** (database query, cache, external API)
|
||||
6. **Response path** (back through layers to UI)
|
||||
|
||||
Document at least one complete flow end-to-end.
|
||||
|
||||
### 3. Identify Layers
|
||||
|
||||
Determine the architectural layers and their boundaries:
|
||||
|
||||
| Layer | Purpose | Location |
|
||||
|-------|---------|----------|
|
||||
| **Presentation** | UI rendering, user interaction | `src/components/`, `src/pages/` |
|
||||
| **Application** | Use cases, orchestration | `src/services/`, `src/hooks/` |
|
||||
| **Domain** | Business rules, entities | `src/models/`, `src/domain/` |
|
||||
| **Infrastructure** | Database, external APIs, file system | `src/db/`, `src/integrations/` |
|
||||
|
||||
Note: Not all codebases have clean layers. Document what you actually find, including layer violations.
|
||||
|
||||
### 4. Map External Integrations
|
||||
|
||||
List every external system the codebase talks to:
|
||||
|
||||
| Integration | Purpose | Protocol | Location in Code |
|
||||
|-------------|---------|----------|-----------------|
|
||||
| PostgreSQL | Primary data store | SQL via ORM | `src/db/` |
|
||||
| Stripe | Payment processing | REST API | `src/payments/` |
|
||||
| SendGrid | Email delivery | REST API | `src/notifications/` |
|
||||
| Redis | Caching, sessions | Redis protocol | `src/cache/` |
|
||||
|
||||
### 5. Document State Management
|
||||
|
||||
How does the application manage state?
|
||||
|
||||
- **Frontend:** Global store (Redux, Zustand), context, local state, URL state
|
||||
- **Backend:** Session storage, database, cache, in-memory
|
||||
- **Shared:** How does state sync between client and server?
|
||||
|
||||
### 6. Create Dependency Graph
|
||||
|
||||
Map which modules depend on which:
|
||||
|
||||
- Identify core modules that many things depend on (high fan-in)
|
||||
- Identify modules that depend on many things (high fan-out)
|
||||
- Look for circular dependencies
|
||||
- Note tightly coupled vs loosely coupled areas
|
||||
|
||||
### 7. Identify Architectural Patterns
|
||||
|
||||
Document patterns you observe:
|
||||
|
||||
- **Structural:** MVC, MVVM, Clean Architecture, Hexagonal, Monolith, Microservices
|
||||
- **Data:** Repository pattern, Active Record, Data Mapper, CQRS
|
||||
- **Communication:** REST, GraphQL, WebSocket, Event-driven, Message queue
|
||||
- **Error handling:** Centralized, per-module, try-catch patterns, error boundaries
|
||||
- **Testing:** Unit/integration/e2e split, mocking approach, test data strategy
|
||||
|
||||
### 8. Verify Checklist
|
||||
|
||||
- [ ] Component/module inventory created
|
||||
- [ ] At least one data flow traced end-to-end
|
||||
- [ ] Architectural layers identified
|
||||
- [ ] External integrations mapped
|
||||
- [ ] State management approach documented
|
||||
- [ ] Key dependencies mapped (especially high fan-in/fan-out)
|
||||
- [ ] Architectural patterns identified
|
||||
|
||||
### 9. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 4: Document Findings"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- User can chat or ask questions - always respond and then redisplay menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN the architectural mapping is complete with components, flows, and dependencies documented will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Component/module inventory created
|
||||
- At least one data flow traced end-to-end
|
||||
- Architectural layers identified
|
||||
- External integrations mapped
|
||||
- State management approach documented
|
||||
- Key dependencies mapped (especially high fan-in/fan-out)
|
||||
- Architectural patterns identified
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Skipping data flow tracing
|
||||
- Not mapping external integrations
|
||||
- Beginning final document creation before analysis is complete
|
||||
- Ignoring dependency relationships
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,242 @@
|
||||
---
|
||||
name: 'step-04-document-findings'
|
||||
description: 'Create a structured architecture document that answers the original questions, includes diagrams, and provides actionable recommendations'
|
||||
|
||||
# File References
|
||||
activityWorkflowFile: '../workflow-analysis.md'
|
||||
---
|
||||
|
||||
# Step 4: Document Findings
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Create a structured architecture document that answers the original questions, includes diagrams, and provides actionable recommendations.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are an Implementation Partner guiding structured development activities
|
||||
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
|
||||
- ✅ Maintain clear and structured tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on creating the final architecture document with diagrams and recommendations
|
||||
- 🚫 FORBIDDEN to redo analysis — use findings from Steps 2 and 3
|
||||
- 💬 Approach: Collaboratively structure and write the document with user, ensuring original questions are answered
|
||||
- 📋 Include at least one Mermaid diagram and prioritized recommendations
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Produce a complete architecture document answering the original questions
|
||||
- 💾 Save the document to the project's output location
|
||||
- 📖 Reference all findings from Steps 1-3
|
||||
- 🚫 Do not restart analysis — synthesize existing findings
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Question and scope from Step 1; scan from Step 2; architecture map from Step 3
|
||||
- Focus: Document synthesis, diagrams, risk assessment, recommendations
|
||||
- Limits: No new analysis — document what was found
|
||||
- Dependencies: Steps 1, 2, and 3 must be complete
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Create the Architecture Document
|
||||
|
||||
Create a document in the output folder that answers the questions defined in Step 01. Use this structure:
|
||||
|
||||
```markdown
|
||||
# Architecture Analysis: [Project Name]
|
||||
|
||||
**Date:** [Date]
|
||||
**Scope:** [What was analyzed]
|
||||
**Questions:** [Original questions from Step 01]
|
||||
|
||||
## Summary
|
||||
|
||||
[2-3 sentence overview of key findings]
|
||||
|
||||
## Tech Stack
|
||||
|
||||
[Language, framework, database, infrastructure — from Step 02]
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
[High-level description of how the system is structured]
|
||||
|
||||
### Architecture Diagram
|
||||
|
||||
[Mermaid diagram — see below]
|
||||
|
||||
## Component Map
|
||||
|
||||
[Module inventory with responsibilities — from Step 03]
|
||||
|
||||
## Data Flow
|
||||
|
||||
[End-to-end flow traces — from Step 03]
|
||||
|
||||
## Dependencies
|
||||
|
||||
[Key dependency relationships, high fan-in/fan-out modules]
|
||||
|
||||
## Patterns and Conventions
|
||||
|
||||
[Architectural and code patterns observed]
|
||||
|
||||
## Risks and Tech Debt
|
||||
|
||||
[Issues found during analysis]
|
||||
|
||||
## Recommendations
|
||||
|
||||
[Actionable next steps]
|
||||
```
|
||||
|
||||
### 2. Include Diagrams
|
||||
|
||||
Use Mermaid syntax for diagrams that render in Markdown viewers.
|
||||
|
||||
**Architecture diagram example:**
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Client[Browser] --> API[API Server]
|
||||
API --> Auth[Auth Service]
|
||||
API --> Users[User Service]
|
||||
API --> Payments[Payment Service]
|
||||
Users --> DB[(PostgreSQL)]
|
||||
Payments --> Stripe[Stripe API]
|
||||
Auth --> Redis[(Redis)]
|
||||
```
|
||||
|
||||
**Dependency diagram example:**
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Module A] --> C[Core]
|
||||
B[Module B] --> C
|
||||
B --> D[Module D]
|
||||
D --> C
|
||||
```
|
||||
|
||||
**Data flow example:**
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
User->>Frontend: Click "Submit"
|
||||
Frontend->>API: POST /orders
|
||||
API->>Validation: Validate input
|
||||
API->>OrderService: Create order
|
||||
OrderService->>Database: INSERT order
|
||||
OrderService->>PaymentService: Charge card
|
||||
PaymentService->>Stripe: Create charge
|
||||
Stripe-->>PaymentService: Charge confirmed
|
||||
PaymentService-->>API: Payment success
|
||||
API-->>Frontend: 201 Created
|
||||
Frontend-->>User: Show confirmation
|
||||
```
|
||||
|
||||
### 3. Document Risks and Tech Debt
|
||||
|
||||
For each risk or debt item found during analysis:
|
||||
|
||||
| Risk | Severity | Location | Impact |
|
||||
|------|----------|----------|--------|
|
||||
| No input validation on `/api/admin/` routes | High | `src/routes/admin.ts` | Security vulnerability |
|
||||
| Circular dependency between User and Order modules | Medium | `src/services/` | Fragile, hard to test |
|
||||
| No error handling in payment flow | High | `src/payments/stripe.ts` | Silent failures |
|
||||
| Outdated dependencies (2 major versions behind) | Medium | `package.json` | Security + compatibility |
|
||||
|
||||
### 4. Write Recommendations
|
||||
|
||||
Each recommendation should be:
|
||||
|
||||
- **Specific** — Name the module, file, or pattern
|
||||
- **Actionable** — Describe what to do, not just what is wrong
|
||||
- **Prioritized** — Order by impact and effort
|
||||
|
||||
Example:
|
||||
|
||||
```markdown
|
||||
## Recommendations
|
||||
|
||||
1. **Add input validation to admin routes** (High priority, low effort)
|
||||
- Add Zod schemas to all `/api/admin/` endpoints
|
||||
- Estimated: 2-3 hours
|
||||
|
||||
2. **Break circular dependency between User and Order** (Medium priority, medium effort)
|
||||
- Extract shared types to a common module
|
||||
- Use dependency injection for cross-service calls
|
||||
- Estimated: 4-6 hours
|
||||
|
||||
3. **Add error handling to payment flow** (High priority, medium effort)
|
||||
- Wrap Stripe calls in try-catch with structured error responses
|
||||
- Add retry logic for transient failures
|
||||
- Estimated: 3-4 hours
|
||||
```
|
||||
|
||||
### 5. Save Output
|
||||
|
||||
Save the document to the project's output location. If no output location is defined, save to:
|
||||
|
||||
- `docs/architecture/` in the analyzed project, or
|
||||
- The agent experiences folder for session insights
|
||||
|
||||
### 6. Verify Checklist
|
||||
|
||||
- [ ] Document answers the original questions from Step 01
|
||||
- [ ] Summary is clear and concise (2-3 sentences)
|
||||
- [ ] At least one Mermaid diagram included
|
||||
- [ ] Risks and tech debt listed with severity
|
||||
- [ ] Recommendations are specific, actionable, and prioritized
|
||||
- [ ] Document saved to output folder
|
||||
|
||||
### 7. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [M] Return to Activity Menu"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF M: Update design log, then load, read entire file, then execute {activityWorkflowFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed when user selects 'M'
|
||||
- User can chat or ask questions - always respond and then redisplay menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN the architecture document is complete and saved will you then load and read fully `{activityWorkflowFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Document answers the original questions from Step 01
|
||||
- Summary is clear and concise (2-3 sentences)
|
||||
- At least one Mermaid diagram included
|
||||
- Risks and tech debt listed with severity
|
||||
- Recommendations are specific, actionable, and prioritized
|
||||
- Document saved to output folder
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Document does not answer original questions
|
||||
- No diagrams included
|
||||
- Recommendations are vague or not prioritized
|
||||
- Document not saved
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
Reference in New Issue
Block a user