tomevault-io Executing X-Fidelity Engineering Plans
This skill guides the xfi-planner agent through executing comprehensive engineering plans by coordinating subagents.
Prerequisites
- An existing plan in
knowledge/plans/[yyyymmdd]-[feature-name]/ - Plan status should be "Ready for Review" or "In Progress"
- All subtask files should exist and be complete
Workflow Overview
┌─────────────────────────────────────────────────────────────┐
│ 1. Load and analyze plan index and subtask files │
├─────────────────────────────────────────────────────────────┤
│ 2. USER STOP: Confirm execution summary │
├─────────────────────────────────────────────────────────────┤
│ 3. Execute subtasks per dependency graph │
├─────────────────────────────────────────────────────────────┤
│ 4. Capture and review results from each subagent │
├─────────────────────────────────────────────────────────────┤
│ 5. Update index with progress │
├─────────────────────────────────────────────────────────────┤
│ 6. Verify all subtasks and DoD complete │
├─────────────────────────────────────────────────────────────┤
│ 7. Final review (code, design, tests) │
├─────────────────────────────────────────────────────────────┤
│ 8. USER STOP: Review and approve changes │
├─────────────────────────────────────────────────────────────┤
│ 9. Documentation and knowledge capture │
├─────────────────────────────────────────────────────────────┤
│ 10. Mark plan completed │
└─────────────────────────────────────────────────────────────┘
Step 1: Load and Analyze Plan
Read Plan Files
- List available plans in
knowledge/plans/ - Read the selected plan's index file
- Read all subtask files
- Analyze the dependency graph
Validation Checks
- Index file exists and is complete
- All referenced subtask files exist
- Dependency graph is valid (no cycles)
- Each subtask has assigned subagent
- Definition of done is clear for each subtask
Step 2: User Confirmation (MANDATORY STOP)
STOP and present execution summary:
## Plan Execution Summary
### Plan: [Feature Name]
**Directory**: `knowledge/plans/[yyyymmdd]-[feature-name]/`
**Status**: Ready for Execution
### Execution Phases
#### Phase 1 (Parallel)
| Subtask | File | Subagent | Deliverables |
|---------|------|----------|--------------|
| 01 | subtask-01-... | xfi-engineer | [Brief summary] |
| 02 | subtask-02-... | xfi-engineer | [Brief summary] |
#### Phase 2 (After Phase 1)
| Subtask | File | Subagent | Deliverables |
|---------|------|----------|--------------|
| 03 | subtask-03-... | xfi-engineer | [Brief summary] |
### Total Work
- Subtasks: [N]
- Subagent invocations: [N]
- Parallel phases: [N]
- Sequential phases: [N]
### Risk Factors
- [Any identified risks from plan]
---
Proceed with execution? (yes/no)
Wait for user confirmation before proceeding.
Step 3: Execute Subtasks
Parallel Execution
For subtasks that can run in parallel (no dependencies on each other):
Invoke multiple subagents simultaneously:
For each subtask in current phase:
Invoke [assigned-subagent] with:
"Execute the engineering task defined in this subtask file:
**Subtask File**: knowledge/plans/[plan-dir]/[subtask-file].md
**IMPORTANT INSTRUCTIONS**:
1. Read the subtask file carefully
2. Implement all deliverables listed
3. Follow the testing strategy (NO global tests)
4. Update the 'Execution Notes' section in the subtask file when done
5. Report back with summary of work completed
**Constraints**:
- Only modify files related to this subtask
- Do NOT run global test suites
- Create targeted tests for your changes
- Skip test execution if files may be modified by parallel agents
When complete, update the subtask file's Execution Notes section with:
- Agent session info
- Work log
- Any blockers encountered
- List of files modified"
Sequential Execution
For subtasks with dependencies:
- Wait for all dependency subtasks to complete
- Verify dependency subtasks' execution notes are filled
- Then invoke the dependent subtask's subagent
Tracking Progress
After each subagent completes:
- Read the updated subtask file to verify completion
- Update the index file completion checklist:
## Completion Checklist - [x] Subtask 01: Completed - [brief summary] - [x] Subtask 02: Completed - [brief summary] - [ ] Subtask 03: In Progress - Note any blockers for resolution
Step 4: Capture and Review Results
After Each Subtask Completion
Read the subtask's execution notes:
- Files modified
- Tests created
- Any issues encountered
- Blockers that need resolution
Handle Blockers
If a subtask reports blockers:
- Analyze the blocker
- Determine if it blocks other subtasks
- Either resolve directly or invoke appropriate subagent
- Update subtask file with resolution
Update Index Execution Notes
## Execution Notes
### Phase 1 Completed: [timestamp]
- Subtask 01: [summary of changes]
- Subtask 02: [summary of changes]
### Phase 2 Completed: [timestamp]
- Subtask 03: [summary of changes]
### Issues Encountered
- [Issue 1]: [How it was resolved]
Step 5: Verify Completion
Completion Loop
After all subtasks complete, verify:
- All subtask execution notes filled
- All deliverables checked off
- No outstanding blockers
If any items incomplete:
Re-invoke the relevant subagent:
"The subtask at [path] has incomplete items:
Incomplete deliverables:
- [List unchecked items]
Please complete these items and update the execution notes."
Loop until all complete.
Step 6: Final Review Phase
Invoke reviewers in parallel:
xfi-code-reviewer
Invoke xfi-code-reviewer subagent with:
"Perform a comprehensive code review of all changes from plan execution:
Plan: knowledge/plans/[plan-dir]/
Files modified (from subtask execution notes):
[Aggregate list of all modified files]
Review for:
1. Code quality and patterns
2. Error handling
3. Type safety
4. Security concerns
5. Test coverage
Provide a review report with any issues found."
xfi-system-design
Invoke xfi-system-design subagent with:
"Review the implemented changes for architectural consistency:
Plan: knowledge/plans/[plan-dir]/
Files modified (from subtask execution notes):
[Aggregate list of all modified files]
Review for:
1. Alignment with original design
2. Package boundary adherence
3. Pattern consistency
4. Any architectural concerns
Provide a review report."
xfi-testing-expert
Invoke xfi-testing-expert subagent with:
"Verify test coverage and run the global test suite:
Plan: knowledge/plans/[plan-dir]/
Files modified (from subtask execution notes):
[Aggregate list of all modified files]
Tasks:
1. Verify all new code has tests
2. Run global test suite: yarn test
3. Fix any failing tests
4. Report coverage status
Continue until all tests pass."
Handle Review Issues
If reviewers find issues:
- Invoke appropriate subagent to fix
- Re-run affected reviews
- Loop until all reviews pass
Update Index
## Completion Checklist
- [x] Subtask 01: Completed
- [x] Subtask 02: Completed
- [x] Subtask 03: Completed
- [x] Final code review: Passed - [summary]
- [x] Final architecture review: Passed - [summary]
- [x] Global tests verified: All passing
Step 7: User Review (MANDATORY STOP)
STOP and present for user approval:
## Plan Execution Complete - Awaiting Review
### Plan: [Feature Name]
### Summary of Changes
#### Files Modified
[Aggregate list from all subtasks]
#### Key Accomplishments
1. [Major accomplishment 1]
2. [Major accomplishment 2]
3. [Major accomplishment 3]
### Review Status
- Code Review: PASSED
- Architecture Review: PASSED
- Test Suite: ALL PASSING
### Issues Resolved During Execution
- [Issue 1]: [Resolution]
### Pending Actions (after your approval)
1. Documentation update by xfi-docs-expert
2. Knowledge capture by xfi-system-design
---
Please review the changes. When satisfied, confirm to proceed with documentation and finalization.
Wait for user approval.
Step 8: Documentation and Knowledge Capture
After user approval, invoke in parallel:
xfi-docs-expert
Invoke xfi-docs-expert subagent with:
"Update documentation for the completed plan:
Plan: knowledge/plans/[plan-dir]/
Changes implemented:
[Summary of all changes]
Tasks:
1. Update README.md if needed
2. Update website docs if user-facing changes
3. Update any affected package documentation
4. Update CHANGELOG if applicable
Report what was updated."
xfi-system-design
Invoke xfi-system-design subagent with:
"Capture knowledge from the completed plan:
Plan: knowledge/plans/[plan-dir]/
Tasks:
1. Update architecture documentation if patterns changed
2. Add learnings to knowledge/ directory
3. Update any affected design documents
4. Note any patterns for future reference
Report what was captured."
Step 9: Mark Plan Complete
Update the index file:
## Status
Completed
## Completion Summary
- **Started**: [timestamp]
- **Completed**: [timestamp]
- **Subtasks Executed**: [N]
- **Files Modified**: [N]
- **Tests Added**: [N]
## Final Documentation
- README updates: [Yes/No - summary]
- Website updates: [Yes/No - summary]
- Knowledge captured: [Yes/No - summary]
## Lessons Learned
- [Lesson 1]
- [Lesson 2]
Notify user:
## Plan Completed Successfully
### Plan: [Feature Name]
**Status**: COMPLETED
### Final Summary
- All [N] subtasks completed
- [N] files modified
- All tests passing
- Documentation updated
- Knowledge captured
The plan has been marked complete. All changes are in place.
Critical Rules
- ALWAYS stop for user confirmation at Steps 2 and 7
- FOLLOW dependency graph - never execute dependent tasks before dependencies
- UPDATE index file after each major milestone
- VERIFY completion before proceeding to next phase
- HANDLE blockers promptly - don't leave subtasks stuck
- RUN global tests only in final review phase
- CAPTURE knowledge for future reference
Troubleshooting
Subtask Agent Fails
- Read the error details
- Determine if it's a transient or permanent issue
- Re-invoke with additional context if needed
- Update subtask file with issue notes
Tests Fail in Final Phase
- Have xfi-testing-expert diagnose
- Invoke xfi-engineer to fix issues
- Re-run tests until passing
- Update affected subtask execution notes
Review Finds Major Issues
- Assess severity of issues
- Create ad-hoc subtasks for fixes
- Re-invoke appropriate subagents
- Loop through review again
Dependency Deadlock
- Re-analyze dependency graph
- Identify circular dependencies
- Break cycle by redefining subtasks
- Update plan and re-execute affected subtasks
Progress Tracking Template
Use this template in the index file:
## Execution Progress
| Phase | Subtask | Status | Started | Completed | Notes |
|-------|---------|--------|---------|-----------|-------|
| 1 | 01 | Completed | [time] | [time] | [notes] |
| 1 | 02 | Completed | [time] | [time] | [notes] |
| 2 | 03 | In Progress | [time] | - | [notes] |
| 3 | 04 | Pending | - | - | - |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.