speccrew-dev-backend

name	speccrew-dev-backend
description	Backend Development SOP. Guide System Developer Agent to implement backend code according to system design documents. Reads design blueprints, extracts task checklist, and executes implementation task by task with local quality checks.
tools	Bash, Edit, Write, Glob, Grep, Read

Trigger Scenarios

• Backend system design has been approved, user requests backend development
• User asks "Start backend development", "Implement backend code"
• System Developer Agent receives task to implement backend for a specific platform

Input Parameters

Parameter	Required	Type	Description
design_doc_path	Yes	string	Path to a single module design document (passed by upstream system-developer agent)
platform_id	Yes	string	Platform identifier (e.g., backend-spring, backend-nodejs)
task_id	Yes	string	Task identifier from dispatch context
iteration_id	No	string	Current iteration identifier for progress messages
output_dir	No	string	Output directory for task record (default: auto-derived from iteration path)

AgentFlow Definition

REQUIRED: Before executing this workflow, read the XML workflow specification: speccrew-workspace/docs/rules/agentflow-spec.md

---

Workflow

Absolute Constraints

These rules apply to Task Record document generation. Violation = task failure.

1. FORBIDDEN: create_file for Task Record — NEVER use create_file to write the Task Record document. It MUST be created by copying the template then filling sections with search_replace. create_file produces truncated output on large files.

2. FORBIDDEN: Full-file rewrite — NEVER replace the entire Task Record content in a single operation. Always use targeted search_replace on specific sections.

3. MANDATORY: Template-first workflow — Copy template MUST execute before fill sections. Skipping copy and writing content directly is FORBIDDEN.

4. CLARIFICATION: Source code is NOT template-filled — Actual source code files are written directly based on design blueprints. The template-fill workflow applies ONLY to the Task Record document.

Step 1: Read Design Documents

Input: design_doc_path — Path to a single module design document (passed by upstream system-developer agent).

Read in order:

1. Module Design Document: The design_doc_path provided (single module's design)
2. Platform INDEX: speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md
3. API Contract: speccrew-workspace/iterations/{number}-{type}-{name}/03.api-contract/[feature-name]-api-contract.md
4. Techs Knowledge (from agent context):
   • speccrew-workspace/knowledges/techs/{platform_id}/tech-stack.md
   • speccrew-workspace/knowledges/techs/{platform_id}/architecture.md
   • speccrew-workspace/knowledges/techs/{platform_id}/conventions-design.md
   • speccrew-workspace/knowledges/techs/{platform_id}/conventions-dev.md
   • speccrew-workspace/knowledges/techs/{platform_id}/conventions-data.md (critical: ORM, data modeling, migration)
5. Task Record Template: speccrew-dev-backend/templates/TASK-RECORD-TEMPLATE.md

Step 2: Create Task Record File

Before coding, create the task record using template-fill workflow:

2a Copy Template to Task Record Path

1. Read the template file: templates/TASK-RECORD-TEMPLATE.md
2. Replace top-level placeholders (module name, feature name, platform ID, iteration info)
3. Create the document using create_file:
   • Target path: speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[module]-task.md
   • Content: Template with top-level placeholders replaced
4. Verify: Document has complete section structure ready for filling

2b Fill Task Record Sections Using search_replace

Fill each section with design metadata extracted from input documents.

⚠️ CRITICAL CONSTRAINTS:

• FORBIDDEN: create_file to rewrite the entire document
• MUST use search_replace to fill each section individually
• All section titles MUST be preserved

Step 3: Extract Task List

Parse design documents to extract all implementation tasks.

Backend Task Types

Category	Description	Example Files
Entity/Model	Data model definitions	entity/, model/, domain/
Repository/DAO	Data access layer	repository/, dao/, mapper/
Service	Business logic layer	service/, manager/, handler/
Controller/API	REST endpoints	controller/, router/, api/
Database Migration	Schema changes	db/migration/, migrations/
API Configuration	Route/middleware config	config/, routes/
Middleware/Interceptor	Cross-cutting concerns	middleware/, interceptor/

Task Checklist Table Format

Task ID	Module	Description	Target Files	API Endpoint	DB Migration	Dependencies	Status
BE-001	User	Define User entity	entity/User.java	-	V001__create_user.sql	-	⏳ Pending
BE-002	User	Create UserRepository	repository/UserRepository.java	-	-	BE-001	⏳ Pending
BE-003	Auth	Login endpoint	controller/AuthController.java	POST /auth/login	-	BE-002	⏳ Pending

Status: ⏳ Pending / 🔄 In Progress / ✅ Complete / 🚫 Blocked

Proceed directly to implementation — no user confirmation required.

Step 4: Task-by-Task Implementation

Execute tasks in dependency order.

Implementation Principles

• Follow design document file paths, naming, and structure exactly
• Use actual framework syntax from techs knowledge (not generic pseudo-code)
• Follow conventions-data.md for ORM patterns and migration naming
• Reuse existing code where possible (use Grep to search)
• Directly write code based on design blueprint (no template filling for source code)

Per-Task Workflow

1. Mark task as 🔄 In Progress
2. Implement the code following design specification
3. Run local checks (Step 6)
4. Update status to ✅ Complete if checks pass
5. Record deviations if implementation differs from design

When Design Issues Found

• Stop current task
• Describe issue clearly to user
• Wait for user decision: return to design phase OR proceed with documented deviation

Step 5: Database Migration Verification

This step applies ONLY when the task checklist contains Database Migration tasks. If no migration tasks exist, skip to Step 6.

5.1 Verify Migration Scripts

After all migration-related tasks in Step 4 are complete:

1. Check script existence: Verify all migration scripts listed in the design document's "Migration Requirements" table have been created at the specified paths
2. Check naming convention: Verify script names follow the pattern defined in conventions-data.md Migration Configuration
3. Check script content: Each script must contain valid SQL/DDL (or tool-specific syntax) that matches the Table Schema defined in the design document

5.2 Verify Migration Order

1. Dependency check: Migration scripts with table dependencies must be ordered correctly (e.g., referenced table created before foreign key table)
2. Version sequence: Migration version numbers must be sequential with no gaps

5.3 Report Migration Summary

Add to the task record:

Script Name	Path	Type	Tables Affected	Status
{name}	{path}	CREATE/ALTER	{tables}	Created/Verified

Step 6: Local Checks

After completing each task, run quality checks:

Check Matrix

Check	Command Example	When Required
Compile	mvn compile / gradle build / go build	After code changes
Lint	mvn checkstyle:check / golangci-lint run	After code changes
Unit Tests	mvn test -Dtest=XxxTest / go test ./...	When testable logic added
API Smoke Test	Start service, curl http://localhost:8080/health	After controller changes

Check Failure Handling

• Fix issues before marking task complete
• For complex issues, record in task file "Pending Issues" section
• Do NOT proceed to next task until current task passes checks

Environment Diagnostics

When task is blocked (compile fail, test fail, env issue):

1. Check logs: docker logs [container] --tail 100 or process output
2. Verify services: docker ps / docker compose ps
3. Check environment: .env variables, database connectivity
4. Record diagnosis: symptom → investigation steps → root cause → resolution

Step 7: Record Deviations

If implementation differs from design, record in task file "Deviation Log" section:

### Deviation Log

| Task ID | Design Spec | Actual Implementation | Reason |
|---------|-------------|----------------------|--------|
| BE-003 | Use JWT library A | Used JWT library B | Library A has security vulnerability |

Step 8: Handle Technical Debt

If accepting suboptimal solutions, write to tech-debt directory:

Path: speccrew-workspace/iterations/{number}-{type}-{name}/tech-debt/[module]-tech-debt.md

Use the unified tech_debt document template defined in the workspace document templates configuration.

Helper Scripts Output

All temporary/helper scripts (validation, data init, environment setup, etc.) MUST be saved to:

iterations/{iter}/04.development/{platform_id}/scripts/

Exception: Application source scripts (migrations, seeds) go to the project source directory per conventions-data.md.

Include all generated scripts in the Task Record "Generated Scripts" section with path and purpose.

Step 9: Completion Notification

When all tasks complete, update task record and notify user:

Backend Development Complete: {module-name}
Platform: {platform_id}

Tasks Completed: {X}
├── ✅ Complete: {count}
├── 🚫 Blocked: {count}
└── Deviations: {count}

API Endpoints:
├── Implemented: {count} endpoints
└── Status: See task record for details

Database Changes:
├── New Tables: {count}
├── Modified Tables: {count}
└── Migrations: {count}

Technical Debt: {count} items (see tech-debt/)
Task Record: speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[module]-task.md

Ready for testing phase.

Task Completion Report

At the end of Step 9 (or if the skill fails at any point), output a structured Task Completion Report:

Success Report

## Task Completion Report
- **Status**: SUCCESS
- **Task ID**: {task_id from dispatch context}
- **Platform**: {platform_id}
- **Module**: {module_name}
- **Output Files**:
  - {file_path_1}
  - {file_path_2}
  - ...
- **Migration Scripts**: {count} scripts at {migration_dir}
  - {script_1_name}: {type} ({tables})
  - {script_2_name}: {type} ({tables})
- **Summary**: Backend module {module_name} implemented with {X} tasks completed

Failure Report

If the skill fails at any step:

## Task Completion Report
- **Status**: FAILED
- **Task ID**: {task_id from dispatch context}
- **Platform**: {platform_id}
- **Module**: {module_name}
- **Output Files**: {list of partially generated files, or "None"}
- **Summary**: {one-line description of what was attempted}
- **Error**: {detailed error description}
- **Error Category**: {DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED}
- **Partial Outputs**: {list of files that were generated before failure, or "None"}
- **Recovery Hint**: {suggestion for how to resolve and retry}

Error Category Definitions:

• DEPENDENCY_MISSING: Required runtime/dependency not available
• BUILD_FAILURE: Compilation error, maven/gradle build failure
• VALIDATION_ERROR: Checkstyle, test failure, or validation error
• RUNTIME_ERROR: Service startup failure, runtime exception
• BLOCKED: Blocked by external dependency or unresolved design issue

OUTPUT EFFICIENCY RULES

When executing this skill:

1. Direct-to-File Output: All implementation code, task records, and helper scripts MUST be written directly to output files
2. Minimal Conversation Output: Only output:
   • Block execution announcements (1 line each): "[Block XX] Implementing..."
   • Error messages requiring attention
   • Task Completion Report (final summary)
3. FORBIDDEN in conversation:
   • ❌ Full source code blocks or file contents
   • ❌ Complete implementation listings
   • ❌ Large configuration file dumps
   • ❌ Architecture diagrams displayed in chat
   • ❌ API endpoint listings longer than 3 lines
4. Rationale: Workers run in batch mode (up to 6 concurrent). Displaying code content in conversation wastes context window and provides no value since content goes to files anyway.

ABORT CONDITIONS

When script execution or build/compile fails:

1. STOP immediately — Report: Task ID, error message, failed command
2. FORBIDDEN responses on failure:
   • ❌ DO NOT provide A/B/C alternative options
   • ❌ DO NOT suggest "skip this step and continue"
   • ❌ DO NOT run ad-hoc PowerShell/Bash commands as workaround
   • ❌ DO NOT create temporary scripts to work around the issue
3. ONLY correct response: Report the failure in Task Completion Report with status FAILED and error details

OUTPUT EFFICIENCY RULES

When executing this skill:

1. Direct-to-File Output: All implementation code, task records, and helper scripts MUST be written directly to output files
2. Minimal Conversation Output: Only output:
   • Block execution announcements (1 line each): "[Block XX] Implementing..."
   • Error messages requiring attention
   • Task Completion Report (final summary)
3. FORBIDDEN in conversation:
   • ❌ Full source code blocks or file contents
   • ❌ Complete implementation listings
   • ❌ Large configuration file dumps
   • ❌ Architecture diagrams displayed in chat
   • ❌ API endpoint listings longer than 3 lines
4. Rationale: Workers run in batch mode (up to 6 concurrent). Displaying code content in conversation wastes context window and provides no value since content goes to files anyway.

ABORT CONDITIONS

When script execution or build/compile fails:

1. STOP immediately — Report: Task ID, error message, failed command
2. FORBIDDEN responses on failure:
   • ❌ DO NOT provide A/B/C alternative options
   • ❌ DO NOT suggest "skip this step and continue"
   • ❌ DO NOT run ad-hoc PowerShell/Bash commands as workaround
   • ❌ DO NOT create temporary scripts to work around the issue
3. ONLY correct response: Report the failure in Task Completion Report with status FAILED and error details

Key Rules

Rule	Description
Blueprint-Driven	Implement directly from system design, no template filling for source code
Actual Framework Syntax	Use real framework annotations/syntax from techs knowledge
API Contract is READ-ONLY	Do NOT modify API Contract; report issues if found
Task List Required	Must extract and record task list before implementation
Per-Task Quality Gates	Each task must pass local checks before proceeding
Deviation Recording	ALL deviations from design must be documented
Tech Debt Tracking	Suboptimal solutions written to tech-debt/ directory

Reference Guides

Mermaid Diagram Requirements

When generating Mermaid diagrams, follow compatibility guidelines:

• Use only basic node definitions: A[text content]
• No HTML tags (e.g., <br/>)
• No nested subgraphs
• No direction keyword
• No style definitions
• No special characters in node text
• Use standard graph TB/LR or flowchart TD/LR or erDiagram syntax only

---

Checklist

• All design documents and techs knowledge loaded before implementation
• Task record file created with complete checklist
• Task list extracted and recorded in task file
• Each task marked in progress before coding
• Local checks run after each task (compile/lint/test/smoke)
• Code follows conventions-data.md ORM patterns
• Database migrations follow naming conventions
• API endpoints match API Contract specifications
• All deviations recorded in task file
• Technical debt written to tech-debt/ directory (if any)
• Task record status updated to complete
• All Mermaid diagrams follow compatibility guidelines