dev-swarm-code-development

# AI Builder - Code Development This skill implements backlogs through a structured feature-driven approach. As a Software Engineer expert, you'll read backlog requirements, reference existing features, design implementation approach, write code, and create comprehensive documentation for the features knowledge base. ## When to Use This Skill - User asks to implement a backlog - User requests to complete a feature, change, bug fix, or improvement - User says "develop backlog X" - User wants to implement work from sprint - User asks to code a specific backlog item ## Prerequisites This skill requires: - `04-prd/` - Product Requirements Document (business requirements and acceptance criteria) - `07-tech-specs/` - Engineering standards and constraints - `10-sprints/` folder with active sprint and backlogs - `features/` folder with features-index.md (existing features knowledge base) - Understanding of the backlog type: FEATURE, CHANGE, BUG, or IMPROVE ## Feature-Driven Development Workflow **CRITICAL:** This skill follows a strict feature-driven approach where `feature-name` is the index for the entire project: **For Each Backlog:** 1. Read `backlog` from `10-sprints/SPRINT-XX-descriptive-name/[BACKLOG_TYPE]-XX-[feature-name]-<sub-feature>.md` 2. Extract the `feature-name` from the backlog file name 3. Read `features/features-index.md` to find the feature file 4. Read feature documentation in this order: - `features/[feature-name].md` - Feature definition (WHAT/WHY/SCOPE) - `features/flows/[feature-name].md` - User flows and process flows (if exists) - `features/contracts/[feature-name].md` - API/data contracts (if exists) - `features/impl/[feature-name].md` - Implementation notes (if exists) 5. Locate source code at `{SRC}/` using `features/impl/[feature-name].md` 6. Implement the code following `07-tech-specs/` 7. Update `backlog` with development notes This approach ensures AI developers can work on large projects without reading all code at once. ## Your Roles in This Skill See `dev-swarm/docs/general-dev-stage-rule.md` for role selection guidance. ## Role Communication See `dev-swarm/docs/general-dev-stage-rule.md` for the required role announcement format. ## Instructions Follow these steps in order for coding development: ### Step 0: Verify Prerequisites and Gather Context **IMPORTANT:** Follow this exact order to efficiently locate all relevant context: 1. **Identify the backlog:** - User specifies which backlog to work on - Or you select next backlog from `10-sprints/` in order ``` 10-sprints/ └── SPRINT-XX-descriptive-name/ └── [BACKLOG_TYPE]-XX-[feature-name]-<sub-feature>.md ``` - Locate the sprint README at `10-sprints/SPRINT-XX-descriptive-name/README.md` for required progress log updates 2. **Read the backlog file:** - Understand task description and requirements - Note backlog type (FEATURE/CHANGE/BUG/IMPROVE) - **Extract the `feature-name`** from the file name (CRITICAL) - Verify `Feature Name` in backlog metadata matches the file name - If they do not match, stop and ask the user to confirm the correct feature name - Review test plan requirements - Identify acceptance criteria 3. **Read source code structure standards:** - Read `dev-swarm/docs/source-code-structure.md` for general guidelines - Note file naming conventions and directory structure 4. **Read PRD and tech specs:** - Read `04-prd/` (all markdown files) - Product requirements and acceptance criteria for the feature - Read `07-tech-specs/` (all markdown files) - Technical specifications and engineering standards - Understand the business context and technical constraints 5. **Read feature documentation (using feature-name as index):** - Read `features/features-index.md` to confirm feature exists - Read `features/[feature-name].md` - Feature definition (WHAT/WHY/SCOPE) - Read `features/flows/[feature-name].md` - User flows (if exists) - Read `features/contracts/[feature-name].md` - API contracts (if exists) - Read `features/impl/[feature-name].md` - Implementation notes (if exists) 6. **Locate existing source code:** - Use `features/impl/[feature-name].md` to find code locations - Navigate to `{SRC}/` directory - Review existing code structure and patterns - Identify files to modify (CHANGE/BUG/IMPROVE) or create (FEATURE) 7. **Understand codebase patterns:** - Review existing code in `{SRC}/` using locations from `features/impl/[feature-name].md` - Note architectural patterns and integration points **DO NOT** read the entire codebase. Use `features/impl/[feature-name].md` to find only relevant files in `{SRC}/`. ### Step 1: Design the Implementation Before writing code, create the feature design document: 1. Create/Update file `features/{feature-name}.md` - If backlog type is `feature` and the related feature file is not exist, create new feature file - If backlog type is `change/bug/improve` or the feature file is exist, update existing feature file - Use the provided templates for consistency 2. Create/update `flow` and `contract` files if it is needed - `features/flows/{feature-name}.md` - User flows and process flows (when needed) - `features/contracts/{feature-name}.md` - API contracts and interfaces (when needed) 3. Present design to user for approval - Show the feature design document - Explain approach and rationale - Highlight any assumptions or decisions - Wait for user confirmation before proceeding ### Step 2: Implement the Code (After User Confirms) Once user approves the design: 1. **Organize code in {SRC}/:** - Follow `dev-swarm/docs/source-code-structure.md` for file organization guidelines - Place code in appropriate locations within `{SRC}/` - Use file naming conventions defined in source-code-structure.md 2. **Write the code:** - Implement according to the approved design - Follow coding standards - Write clean, modular, maintainable code - Include appropriate error handling - Avoid over-engineering (keep it simple) 3. **Code quality guidelines:** - **Modular**: Break code into small, focused functions/components - **Readable**: Clear variable names, self-documenting code - **Simple**: Don't add features not in requirements - **Consistent**: Match style of existing codebase - **Secure**: No XSS, SQL injection, command injection, or OWASP vulnerabilities - **Tested**: Code should be testable per backlog test plan 3. **What NOT to do:** - Don't add extra features beyond requirements - Don't over-abstract or create unnecessary helpers - Don't add comments to code you didn't change - Don't refactor code outside scope of backlog - Don't add hypothetical error handling - Don't create backwards-compatibility hacks 4. **For different backlog types:** **Feature (new functionality):** - Create new files/components - Integrate with existing system - Follow established patterns **Change (modify existing feature):** - Update existing code - Maintain compatibility where needed - Update related code if necessary **Bug (fix defect):** - Fix the specific issue - Avoid changing unrelated code - Verify fix matches test plan **Improve (optimize existing code):** - Refactor/optimize as specified - Maintain same functionality - Document performance improvements ### Step 3: Create Implementation Documentation After code is complete, create implementation documentation: 1. Create `features/impl/{feature-name}.md` **Files Changed:** - List all files created or modified - For each file, note key changes - Use file paths, function names as keywords (NOT line numbers) **Implementation Details:** - Describe how the feature was implemented - Key functions/components created - Integration points with other features - Any important implementation decisions **Code Structure:** - Directory organization - Module/component breakdown - Dependencies added **Key Functions/APIs:** - List important functions with descriptions - Document key API endpoints - Note important classes/components **Reference for Developers:** - Quick keywords for code search - How to find relevant code - Common use patterns 2. Update `features/{feature-name}.md` if needed - Add any insights discovered during implementation - Note if actual implementation differs from design (explain why) - Keep it synchronized with current code 3. Update `features/features-index.md` if needed 4. **Update or create `{SRC}/README.md` (Project Documentation):** - **IMPORTANT**: Developers should maintain project documentation in `{SRC}/README.md`, NOT in the root README.md - Add or update feature documentation: - Feature overview and purpose - Installation and setup instructions - Usage examples and API documentation - Configuration options - Troubleshooting tips - Keep `{SRC}/README.md` as the primary technical reference for developers - Include links to `features/` documentation for detailed specs ### Step 4: Verify Against Test Plan Before marking complete: 1. **Review backlog test plan:** - Ensure code meets all test requirements - Verify acceptance criteria are met 2. **Self-test (if possible):** - Run the code - Test key functionality - Verify no obvious errors 3. **Document test status:** - Note if manual testing was done - List any test results - Flag anything needing QA attention ### Step 5: Finalize and Commit **CRITICAL:** Follow this process to safely commit changes and update tracking: 1. **Update Tracking Files:** - Update `backlog.md`: - Change status from "Not Started" to "In Code Review" - Add "Development Notes" section: - **Files Created/Modified:** List changes - **Implementation Approach:** Summary of work - **Key Decisions:** Technical choices - **Links:** To feature docs and impl docs - Update `10-sprints/.../README.md`: - Update status in table - Add progress log entry 2. **Request Human Review:** - Present the work and the plan to commit - Ask user: "Please review the changes. If approved, I will commit the code and update the backlog." - **Wait for approval.** 3. **Commit the Code (Content):** - Run `git add .` to stage all changes - **Unstage** the backlog file and sprint README (`git reset HEAD <path-to-backlog> <path-to-sprint-readme>`) to keep metadata separate - Check if there are staged changes: - **If yes:** - Draft conventional commit message (e.g., "feat: implement [feature-name]") - Commit: `git commit -m "feat: ..."` - Get Commit ID: `git rev-parse --short HEAD` - **If no** (only docs/metadata changed): - Skip to next step 4. **Update Backlog with Commit ID:** - If a code commit was made, append "**Implementation Commit:** `[commit-id]`" to the "Development Notes" in `backlog.md` 5. **Commit the Backlog (Metadata):** - Stage `backlog.md` and sprint `README.md` - Commit: `git commit -m "docs([feature-name]): update backlog status to In Code Review"` 6. **Notify user:** - Confirm completion - Suggest next step: "Ready for code review" **This two-step commit process ensures code history is preserved before the backlog is updated with the commit reference.** ## Expected File Structure ``` project-root/ ├── 10-sprints/ │ └── SPRINT-XX-descriptive-name/ │ └── [BACKLOG_TYPE]-XX-[feature-name]-<sub-feature>.md # Backlog entry point │ ├── features/ # Features knowledge base │ ├── features-index.md # Index of all features │ ├── [feature-name].md # Feature definition (WHAT/WHY/SCOPE) │ ├── flows/ │ │ └── [feature-name].md # User flows (if needed) │ ├── contracts/ │ │ └── [feature-name].md # API contracts (if needed) │ └── impl/ │ └── [feature-name].md # Implementation notes (code locations) │ └── {SRC}/ # Source code ├── README.md # Project documentation (maintained by developers) └── [organized per dev-swarm/docs/source-code-structure.md guidelines] ``` ## File Templates 1. `features-index.md` ```markdown # Features Index - [feature name a](feature-name-a.md) - [feature name b](feature-name-b.md) ``` 2. **feature.md** ```markdown # Title ## Description [The overview for this feature's implementation, for approval, codeo review, trouble shooting or further development] ## References The details of this feature's implementation * [flow](flows/feature-name.md) * [contract](contracts/feature-name.md) * [Implement](impl/feature-name.md) ``` 3. `flows/feature-name.md` - help to understand the code logic - User flow diagrams (mermaid) - Process flows and sequence diagrams - State transitions - Integration flows 4. `contracts/feature-name.md` - the interface between services, pacakges, workflows - REST API used or endpoint definitions - Request/response schemas - Data models and database schemas - Event contracts 5. `impl/feature-name.md` - help to find the code location in the source code file for codeo review, trouble shooting or further development - searchable keywords - function name, class name, even comment text in the file - file path - Dependencies and integration details - Avoid citing line numbers in the code file as any code change will affect the line numbers