docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,135 @@
|
||||
---
|
||||
name: 'step-01-scope-change'
|
||||
description: 'Define exactly what is new, what is modified, and what must remain untouched'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-02-analyze-impact.md'
|
||||
---
|
||||
|
||||
# Step 1: Scope Change
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Define exactly what is new, what is modified, and what must remain untouched.
|
||||
|
||||
## 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 scope: new functionality, existing unchanged functionality, boundary map, and integration points
|
||||
- 🚫 FORBIDDEN to begin analyzing impact or planning implementation — those are later steps
|
||||
- 💬 Approach: Help user categorize all affected areas into new/modified/untouched
|
||||
- 📋 Every integration point must be identified and documented
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Produce a clear boundary map categorizing all areas as new, modified, or untouched
|
||||
- 💾 Update dialog file with scope definition, boundary map, and integration points
|
||||
- 📖 Reference the feature spec or change request
|
||||
- 🚫 Do not analyze dependencies or plan implementation yet
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Feature specification or change request
|
||||
- Focus: Scoping what changes and what stays the same
|
||||
- Limits: No impact analysis, no implementation planning
|
||||
- Dependencies: A feature spec or change request must exist
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Load Feature Spec
|
||||
|
||||
- Read the feature specification or change request
|
||||
- Understand the desired outcome from the user's perspective
|
||||
- Clarify any ambiguities before proceeding
|
||||
|
||||
### 2. List All New Functionality
|
||||
|
||||
- Enumerate every new capability being added
|
||||
- For each item: what it does, where it lives, how the user interacts with it
|
||||
- Note any new UI components, API endpoints, data models, or routes
|
||||
|
||||
### 3. List All Existing Functionality That Must Stay Unchanged
|
||||
|
||||
- Identify every existing feature that is in scope or adjacent
|
||||
- Explicitly state: "This must continue to work exactly as it does now"
|
||||
- Include both direct features and indirect dependencies (e.g., shared components)
|
||||
|
||||
### 4. Create Boundary Map
|
||||
|
||||
Categorize all affected areas:
|
||||
|
||||
| Category | Description | Examples |
|
||||
|----------|-------------|----------|
|
||||
| **New** | Does not exist yet, being added | New page, new API endpoint, new component |
|
||||
| **Modified** | Exists and will be changed | Updated component to accept new props, extended API response |
|
||||
| **Untouched** | Exists and must not change | Existing pages, unrelated features, shared utilities |
|
||||
|
||||
### 5. Identify Integration Points
|
||||
|
||||
- Where does new code connect to existing code?
|
||||
- What interfaces, APIs, or data structures are shared?
|
||||
- Are there shared components that need to support both old and new behavior?
|
||||
- Document each integration point and its risk level
|
||||
|
||||
### 6. Verify Checklist
|
||||
|
||||
- [ ] Feature spec loaded and understood
|
||||
- [ ] New functionality listed
|
||||
- [ ] Existing functionality that must stay unchanged listed
|
||||
- [ ] Boundary map created (new / modified / untouched)
|
||||
- [ ] Integration points identified
|
||||
- [ ] Dialog file updated with scope definition
|
||||
|
||||
### 7. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 2: Analyze Impact"
|
||||
|
||||
#### 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 scope is fully defined with boundary map and integration points will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Feature spec loaded and understood
|
||||
- New functionality listed
|
||||
- Existing functionality that must stay unchanged listed
|
||||
- Boundary map created (new / modified / untouched)
|
||||
- Integration points identified
|
||||
- Dialog file updated with scope definition
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Beginning impact analysis before scope is defined
|
||||
- Not identifying what must remain untouched
|
||||
- Skipping integration point identification
|
||||
- Leaving ambiguities in the feature spec unresolved
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,136 @@
|
||||
---
|
||||
name: 'step-02-analyze-impact'
|
||||
description: 'Understand how the proposed changes affect existing code and identify risks'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-03-plan-implementation.md'
|
||||
---
|
||||
|
||||
# Step 2: Analyze Impact
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Understand how the proposed changes affect existing code, and identify risks.
|
||||
|
||||
## 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 reading affected code, mapping dependencies, identifying breaking change risks, and assessing database/API impacts
|
||||
- 🚫 FORBIDDEN to begin planning or implementing changes — that is a later step
|
||||
- 💬 Approach: Deep dive into affected code with user, mapping what depends on what
|
||||
- 📋 Document a risk assessment table with likelihood, impact, and mitigation
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Produce a dependency map, breaking change risk list, and risk assessment
|
||||
- 💾 Document risk assessment in the dialog file
|
||||
- 📖 Reference the boundary map and integration points from Step 1
|
||||
- 🚫 Do not plan implementation order or write any code
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Scope definition, boundary map, and integration points from Step 1
|
||||
- Focus: Impact analysis — dependencies, risks, breaking changes
|
||||
- Limits: No implementation planning, no code changes
|
||||
- Dependencies: Step 1 must be complete (scope defined)
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Read Code for All Affected Areas
|
||||
|
||||
- Open and read every file identified as "modified" in the boundary map
|
||||
- Read files adjacent to integration points
|
||||
- Understand the current behavior before planning changes
|
||||
|
||||
### 2. Map Dependencies
|
||||
|
||||
- For each modified file, identify:
|
||||
- What imports it / calls it / depends on it
|
||||
- What it imports / calls / depends on
|
||||
- Build a dependency graph (mental or documented) of the affected area
|
||||
- Flag shared utilities, components, or state that multiple features rely on
|
||||
|
||||
### 3. Identify Breaking Change Risks
|
||||
|
||||
- Will any existing interface signatures change?
|
||||
- Will any existing data shapes change?
|
||||
- Could new code paths affect timing or ordering of existing operations?
|
||||
- Are there implicit assumptions in existing code that the new feature violates?
|
||||
|
||||
### 4. Assess Database/API Impacts
|
||||
|
||||
- Are database schema changes needed? (migrations, new tables, altered columns)
|
||||
- Are API contract changes needed? (new endpoints, changed response shapes)
|
||||
- Can changes be additive (non-breaking) or do they require migration?
|
||||
- Will existing clients (other services, mobile apps) be affected?
|
||||
|
||||
### 5. Document What Could Go Wrong
|
||||
|
||||
Write a risk assessment in the dialog file:
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|-----------|--------|------------|
|
||||
| Shared component breaks for existing use | Medium | High | Test all existing consumers |
|
||||
| API change breaks mobile client | Low | High | Make change additive, not breaking |
|
||||
| State management conflict | Medium | Medium | Isolate new state, feature flag |
|
||||
|
||||
### 6. Verify Checklist
|
||||
|
||||
- [ ] All affected code read and understood
|
||||
- [ ] Dependencies mapped
|
||||
- [ ] Breaking change risks identified
|
||||
- [ ] Database/API impacts assessed
|
||||
- [ ] Risk assessment documented in dialog file
|
||||
|
||||
### 7. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 3: Plan Implementation"
|
||||
|
||||
#### 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 impact analysis is complete with dependencies mapped and risks documented will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- All affected code read and understood
|
||||
- Dependencies mapped
|
||||
- Breaking change risks identified
|
||||
- Database/API impacts assessed
|
||||
- Risk assessment documented in dialog file
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Beginning implementation planning without completing impact analysis
|
||||
- Not reading all affected code
|
||||
- Skipping dependency mapping
|
||||
- Not documenting risks
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: 'step-03-plan-implementation'
|
||||
description: 'Create an ordered, incremental implementation plan with verification points'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-04-implement.md'
|
||||
---
|
||||
|
||||
# Step 3: Plan Implementation
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Create an ordered, incremental implementation plan with verification 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 ordering changes, planning incremental commits, defining verification points, and estimating effort
|
||||
- 🚫 FORBIDDEN to begin writing code — that is the next step
|
||||
- 💬 Approach: Collaboratively sequence the implementation with user, ensuring each step leaves the system working
|
||||
- 📋 Each commit must be a complete, working unit with clear verification criteria
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Produce a sequenced implementation plan with verification points between steps
|
||||
- 💾 Write implementation plan to the dialog file
|
||||
- 📖 Reference the scope from Step 1 and risk assessment from Step 2
|
||||
- 🚫 Do not write any code during this step
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Scope and boundary map from Step 1; impact analysis and risks from Step 2
|
||||
- Focus: Implementation planning — order, commits, verification, feature flags
|
||||
- Limits: No code writing
|
||||
- Dependencies: Steps 1 and 2 must be complete
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Order Changes by Dependency
|
||||
|
||||
- Start with foundational changes (data models, utilities, shared logic)
|
||||
- Then build upward: API endpoints, components, pages, integrations
|
||||
- Each step should build on the previous one
|
||||
- No step should depend on a later step
|
||||
|
||||
### 2. Determine If Feature Flags Are Needed
|
||||
|
||||
Use feature flags when:
|
||||
- The change is large enough that partial deployment is risky
|
||||
- The feature needs to be toggled per environment or per user
|
||||
- Rollback needs to be instant (without redeploying)
|
||||
|
||||
If not needed, keep it simple — branches and PRs are sufficient.
|
||||
|
||||
### 3. Plan Incremental Commits
|
||||
|
||||
Each commit should:
|
||||
- Be a complete, working unit (system stays functional after each commit)
|
||||
- Be small enough to review and understand
|
||||
- Have a clear purpose described in its message
|
||||
|
||||
Example plan structure:
|
||||
```
|
||||
Commit 1: Add new data model (no UI, no routes)
|
||||
Commit 2: Add API endpoint for new feature (behind feature flag)
|
||||
Commit 3: Add new component (rendered only in new context)
|
||||
Commit 4: Integrate component into existing page
|
||||
Commit 5: Enable feature, update tests
|
||||
```
|
||||
|
||||
### 4. Define Verification Points
|
||||
|
||||
Between steps, define what to check:
|
||||
- After commit 1: "Run migrations, verify existing queries still work"
|
||||
- After commit 3: "Render component in isolation, verify it matches spec"
|
||||
- After commit 4: "Full regression on existing page, verify new feature appears"
|
||||
|
||||
### 5. Estimate Effort
|
||||
|
||||
- Note which steps are straightforward vs which carry risk
|
||||
- Identify steps that may need designer/stakeholder input
|
||||
- Flag any steps that might require splitting into sub-steps
|
||||
|
||||
### 6. Verify Checklist
|
||||
|
||||
- [ ] Changes ordered by dependency
|
||||
- [ ] Feature flag decision made and documented
|
||||
- [ ] Incremental commits planned (each leaves system working)
|
||||
- [ ] Verification points defined between steps
|
||||
- [ ] Effort estimated, risks flagged
|
||||
- [ ] Implementation plan written to dialog file
|
||||
|
||||
### 7. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 4: Implement"
|
||||
|
||||
#### 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 implementation plan is complete with ordered steps, verification points, and feature flag decisions will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Changes ordered by dependency
|
||||
- Feature flag decision made and documented
|
||||
- Incremental commits planned (each leaves system working)
|
||||
- Verification points defined between steps
|
||||
- Effort estimated, risks flagged
|
||||
- Implementation plan written to dialog file
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Beginning implementation without a complete plan
|
||||
- Planning commits that leave the system in a broken state
|
||||
- Not defining verification points
|
||||
- Skipping feature flag assessment
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
name: 'step-04-implement'
|
||||
description: 'Implement changes incrementally, verifying at each step'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-05-verify-and-document.md'
|
||||
---
|
||||
|
||||
# Step 4: Implement
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Implement changes incrementally, verifying at each step.
|
||||
|
||||
## 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 implementing each planned commit, testing after each, and ensuring backward compatibility
|
||||
- 🚫 FORBIDDEN to skip verification points or proceed with broken tests
|
||||
- 💬 Approach: Execute each planned step methodically — implement, self-check, test, commit
|
||||
- 📋 Backward compatibility must be verified at every commit
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 All planned steps implemented with passing tests and backward compatibility
|
||||
- 💾 Update dialog file with implementation progress after each commit
|
||||
- 📖 Reference the implementation plan from Step 3 and verification points
|
||||
- 🚫 Do not proceed to next commit if current one is broken
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Scope from Step 1; risks from Step 2; implementation plan from Step 3
|
||||
- Focus: Incremental implementation following the plan
|
||||
- Limits: Only implement what is in the plan — no scope creep
|
||||
- Dependencies: Step 3 must be complete (plan exists)
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Create Feature Branch
|
||||
|
||||
- Branch from the current working branch
|
||||
- Use a descriptive name: `feature/<short-description>` or `evolve/<feature-name>`
|
||||
- Commit the branch before making changes
|
||||
|
||||
### 2. Implement Incrementally Per Plan
|
||||
|
||||
For each planned commit:
|
||||
|
||||
1. **Read the plan** — What does this step require?
|
||||
2. **Implement** — Write the code for this step only
|
||||
3. **Self-check** — Does this change stay within its planned scope?
|
||||
4. **Test** — Run relevant tests, verify the step works
|
||||
5. **Commit** — Clean commit with descriptive message
|
||||
|
||||
### 3. Test After Each Step
|
||||
|
||||
- Run the verification point defined in Step 03
|
||||
- If automated tests exist, run them after each commit
|
||||
- If modifying existing features, verify they still work (baseline comparison)
|
||||
- Do not proceed to the next step if the current one is broken
|
||||
|
||||
### 4. Ensure Backward Compatibility at Each Commit
|
||||
|
||||
At every commit, ask:
|
||||
- Does the existing functionality still work?
|
||||
- Can an existing user do everything they could before?
|
||||
- Are any existing API consumers affected?
|
||||
- If a commit breaks backward compatibility, either fix it or add a feature flag
|
||||
|
||||
### 5. Use Feature Flags if Needed
|
||||
|
||||
When the plan calls for feature flags:
|
||||
- Implement the flag check early (before building the feature behind it)
|
||||
- Default to "off" — new feature is hidden until explicitly enabled
|
||||
- Ensure the "off" path is identical to the pre-change behavior
|
||||
- Test both flag states: on (new behavior) and off (old behavior)
|
||||
|
||||
### 6. Verify Checklist
|
||||
|
||||
- [ ] Feature branch created
|
||||
- [ ] Each planned step implemented and committed separately
|
||||
- [ ] Tests pass after each commit
|
||||
- [ ] Backward compatibility verified at each commit
|
||||
- [ ] Feature flags implemented correctly (if applicable)
|
||||
- [ ] Dialog file updated with implementation progress
|
||||
|
||||
### 7. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 5: Verify and Document"
|
||||
|
||||
#### 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 all planned steps are implemented, tested, and committed with backward compatibility verified will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Feature branch created
|
||||
- Each planned step implemented and committed separately
|
||||
- Tests pass after each commit
|
||||
- Backward compatibility verified at each commit
|
||||
- Feature flags implemented correctly (if applicable)
|
||||
- Dialog file updated with implementation progress
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Proceeding to next step with broken tests
|
||||
- Not verifying backward compatibility
|
||||
- Implementing outside the planned scope
|
||||
- Not testing feature flag on/off states
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
name: 'step-05-verify-and-document'
|
||||
description: 'Comprehensive verification of all new and existing functionality, then document and create PR'
|
||||
|
||||
# File References
|
||||
activityWorkflowFile: '../workflow-evolution.md'
|
||||
---
|
||||
|
||||
# Step 5: Verify and Document
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Comprehensive verification of all new and existing functionality, then document and PR.
|
||||
|
||||
## 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 verifying new functionality, running regression, verifying backward compatibility, checking performance, documenting, and creating PR
|
||||
- 🚫 FORBIDDEN to add new features — only verify, fix issues, and document
|
||||
- 💬 Approach: Comprehensive end-to-end verification with user, then collaborative PR creation
|
||||
- 📋 Any regression failure must be fixed before proceeding
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 All new and existing functionality verified, documented, and PR created
|
||||
- 💾 Finalize dialog file with status, deviations, and PR link
|
||||
- 📖 Reference the boundary map from Step 1 for backward compatibility checks
|
||||
- 🚫 Do not add scope — only verify and document
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Scope from Step 1; risks from Step 2; plan from Step 3; implementation from Step 4
|
||||
- Focus: Final verification, documentation, and PR creation
|
||||
- Limits: No new features
|
||||
- Dependencies: Step 4 must be complete (implementation done)
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Test All New Functionality
|
||||
|
||||
- Walk through every new feature end-to-end
|
||||
- Verify against the feature spec — does it do what was requested?
|
||||
- Test happy paths, error paths, and edge cases
|
||||
- Use Puppeteer for measurable UI criteria (text, colors, layout, interactions)
|
||||
|
||||
### 2. Run Regression Suite
|
||||
|
||||
- Run the full test suite (unit, integration, end-to-end)
|
||||
- If no automated suite exists, manually test all core user flows
|
||||
- Pay special attention to areas identified as "modified" or "integration points" in Step 01
|
||||
- Any failure here must be fixed before proceeding
|
||||
|
||||
### 3. Verify Backward Compatibility
|
||||
|
||||
- Test every feature listed as "untouched" in the boundary map
|
||||
- Confirm that existing users see no change in behavior (unless intended)
|
||||
- If feature flags were used, test with flag OFF — behavior must match pre-change baseline
|
||||
- Test with flag ON — new behavior works correctly alongside existing features
|
||||
|
||||
### 4. Performance Check
|
||||
|
||||
- Does the new feature load within acceptable time?
|
||||
- Did the changes increase bundle size significantly?
|
||||
- Are there new network requests that could slow down existing pages?
|
||||
- Check for obvious performance regressions (slow renders, unnecessary re-renders)
|
||||
|
||||
### 5. Document Changes
|
||||
|
||||
- Update the dialog file with final status
|
||||
- Document what was added, what was changed, what was left untouched
|
||||
- Note any deviations from the original plan and why
|
||||
|
||||
### 6. Create PR
|
||||
|
||||
- Write a PR title that summarizes the evolution: `feat: <what was added>`
|
||||
- PR body should include:
|
||||
- **What:** New functionality added
|
||||
- **Why:** Business reason or user need
|
||||
- **How:** Implementation approach (incremental steps, feature flags)
|
||||
- **Testing:** How it was verified, including backward compatibility
|
||||
- **Risks:** Any known risks or areas to watch
|
||||
- Link to the feature spec or dialog file
|
||||
|
||||
### 7. Verify Checklist
|
||||
|
||||
- [ ] All new functionality tested and working
|
||||
- [ ] Regression suite passes
|
||||
- [ ] Backward compatibility verified
|
||||
- [ ] Performance acceptable
|
||||
- [ ] Changes documented in dialog file
|
||||
- [ ] PR created with clear description
|
||||
- [ ] Feature flags documented (if used)
|
||||
- [ ] Dialog file finalized
|
||||
|
||||
### 8. 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 all verification is complete, changes documented, and PR created will you then load and read fully `{activityWorkflowFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- All new functionality tested and working
|
||||
- Regression suite passes
|
||||
- Backward compatibility verified
|
||||
- Performance acceptable
|
||||
- Changes documented in dialog file
|
||||
- PR created with clear description
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Not running regression suite
|
||||
- Not verifying backward compatibility
|
||||
- Skipping performance check
|
||||
- Creating PR without clear description
|
||||
- Not documenting deviations from the plan
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
Reference in New Issue
Block a user