Commands
/complete Command
Finalize features by validating requirements, generating context files, and saving knowledge to the context repository.
The /complete command finalizes features by validating requirements, generating context files, and saving knowledge to the context repository.
Purpose
Validate that all spec requirements are met, review the deviation log, and generate comprehensive context files that capture the knowledge from your feature.
Usage
/complete [optional-final-notes]
Examples
# Basic completion
/complete
# With final notes
/complete All tests passing, authentication fully implemented
# With lessons learned
/complete Argon2 performed better than expected, consider for other security features
# With future considerations
/complete OAuth2 integration planned for next sprint
What It Does
When you run /complete, Buildforce:
- Validates Requirements
- Checks all functional requirements (FR1, FR2, ...) are implemented
- Verifies non-functional requirements (NFR1, NFR2, ...) are met
- Confirms acceptance criteria (AC1, AC2, ...) are satisfied
- Reviews Deviations
- Analyzes all logged deviations
- Extracts lessons learned
- Identifies patterns for future work
- Generates Context Files
- Creates YAML files in
.buildforce/context/ - Captures architectural decisions
- Documents implementation patterns
- Preserves key files and relationships
- Creates YAML files in
- Updates Context Index
- Adds new contexts to
_index.yaml - Creates cross-references to related contexts
- Updates searchable tags
- Adds new contexts to
- Clears Active Spec
- Marks spec as "completed"
- Clears
currentSpecinbuildforce.json - Ready for next feature
- Requires Confirmation
- Shows completion report
- Asks for explicit confirmation
- Once confirmed, knowledge is saved
Completion Validation
Requirements Check
## Requirements Validation
### Functional Requirements
- ✅ FR1: Email/password login returns JWT token
- ✅ FR2: Token refresh endpoint for expired tokens
- ✅ FR3: Middleware validates JWT on protected routes
### Non-Functional Requirements
- ✅ NFR1: Tokens expire after 15 minutes
- ✅ NFR2: Password hashing uses argon2 (deviated from bcrypt)
### Acceptance Criteria
- ✅ AC1: User can login with valid credentials and receive JWT
- ✅ AC2: Invalid credentials return 401 Unauthorized
- ✅ AC3: Expired tokens are rejected by middleware
**Result: All requirements met ✅**
Deviation Review
## Deviation Analysis
3 deviations logged during implementation:
1. **Password Hashing Library**
- Original: bcrypt
- Actual: argon2
- Reason: Better security against GPU attacks
2. **Token Storage**
- Original: Response body
- Actual: httpOnly cookie
- Reason: Better XSS protection
3. **Refresh Token Storage**
- Original: Redis
- Actual: PostgreSQL
- Reason: Redis not configured in production
**Key Insight:** Security considerations drove most deviations.
Consider argon2 and httpOnly cookies for future auth-related features.
Context File Generation
Buildforce extracts knowledge and creates context files:
Generated Context Example
# .buildforce/context/authentication-module.yaml
version: "0.0.29"
id: "authentication-module"
name: "Authentication Module"
type: module
created: "2025-01-05"
description: |
JWT-based authentication with email/password login, token refresh,
and httpOnly cookie storage for XSS protection.
overview: |
Implemented argon2 password hashing, JWT tokens with 15-minute expiration,
and refresh tokens stored in PostgreSQL. Tokens delivered via httpOnly
cookies for enhanced security.
key_decisions:
- decision: "Use argon2 for password hashing"
rationale: "Superior security against GPU brute-force attacks compared to bcrypt"
- decision: "Store tokens in httpOnly cookies"
rationale: "Prevents XSS attacks from stealing tokens via JavaScript"
- decision: "Store refresh tokens in PostgreSQL"
rationale: "Redis not available in production, main database provides sufficient performance"
file_paths:
primary:
- path: "src/auth/service.ts"
purpose: "Authentication business logic and token generation"
- path: "src/auth/middleware.ts"
purpose: "JWT validation middleware"
- path: "src/auth/routes.ts"
purpose: "Authentication API endpoints"
related_context:
- user-management
- api-security
- database-schema
tags:
- authentication
- jwt
- argon2
- security
- cookies
lessons_learned:
- "argon2 outperformed bcrypt in benchmarks"
- "httpOnly cookies require CORS configuration updates"
- "PostgreSQL refresh tokens need periodic cleanup job"
Context Index Update
# .buildforce/context/_index.yaml
contexts:
# ... existing contexts ...
- id: "authentication-module"
file: "authentication.yaml"
type: module
description: "JWT-based authentication with argon2 hashing"
tags: [authentication, jwt, argon2, security]
related_context: [user-management, api-security]
Completion Report
Buildforce presents a final report before saving:
# Completion Report: Add JWT Authentication
## Summary
Successfully implemented JWT-based authentication with email/password login,
token refresh, and enhanced security via argon2 and httpOnly cookies.
## Requirements: All Met ✅
- 3/3 Functional requirements implemented
- 2/2 Non-functional requirements satisfied
- 3/3 Acceptance criteria validated
## Implementation Insights
- 3 deviations logged (security improvements)
- 8 files created/modified
- 12 tests added (all passing)
## Knowledge Captured
Creating context file: `authentication-module.yaml`
- Key decisions documented
- File relationships mapped
- Lessons learned preserved
## Next Steps
- Feature complete and validated
- Context saved to repository
- Ready for production deployment
---
**Confirm completion?** (yes/no)
Type 'yes' to finalize and save context.
When to Run /complete
Run When:
- ✅ Feature is fully implemented
- ✅ All tests pass
- ✅ Requirements validated
- ✅ Code reviewed and polished
- ✅ Worth capturing for team knowledge
Skip When:
- ❌ Temporary fix or experiment
- ❌ Work in progress
- ❌ No significant knowledge to capture
- ❌ Documentation burden exceeds value
Don't Rush to CompleteTake time to validate thoroughly. Run tests, review code, check requirements.
/complete is a commitment that the feature is done—make sure it actually is.After Completion
Once confirmed:
- Context saved - New knowledge in
.buildforce/context/ - Spec archived - Marked as "completed" in spec folder
- State cleared -
currentSpecinbuildforce.jsonset to null - Ready for next - Can start new feature with
/spec
File Structure After Completion
.buildforce/
├── context/
│ ├── _index.yaml # Updated with new context
│ ├── authentication-module.yaml # ← New context file
│ └── ... (existing contexts)
├── specs/
│ └── add-auth-jwt-20250105/
│ ├── research.yaml
│ ├── spec.yaml # Status: completed
│ └── plan.yaml # Final state with deviations
└── buildforce.json # currentSpec: null
Context Files in Action
Your newly created context file becomes searchable for future work:
# Next feature
/research authentication patterns in this codebase
# Buildforce finds your context
✅ Found: authentication-module.yaml
- argon2 password hashing
- httpOnly cookie storage
- JWT 15-minute expiration pattern
Pro Tips
Add Final Notes
/complete Performance exceeded expectations - argon2 hashing at 200ms avg
Notes are captured in context files for future reference.
Review Deviation Log First
Before /complete, review deviations in plan.yaml:
- Do they make sense?
- Are reasons documented?
- Any patterns for future features?
Confirm Context Quality
After Buildforce generates context, review before confirming:
- Are key decisions captured?
- Are file relationships clear?
- Are lessons learned documented?
Commit Everything
After completion, commit both code and context:
git add src/ .buildforce/context/
git commit -m "feat: add JWT authentication
- Implemented argon2 password hashing
- JWT tokens in httpOnly cookies
- Token refresh with PostgreSQL storage
Context: authentication-module.yaml"
git push
Next Steps
- /document Command - Create context without full workflow
- Context Repository - Understand context storage
- Workflow Overview - See complete workflow