Sdd Apply

From the orchestrator:

• artifact_store.mode: auto | engram | openspec | none
• detail_level: concise | standard | deep

Rules:

• If mode resolves to none, do not update project artifacts (including tasks.md); return progress only.
• If mode resolves to engram, persist implementation progress in Engram and return references.
• If mode resolves to openspec, update tasks.md and file artifacts as defined in this skill.

Stack Awareness

Batuta's ecosystem includes the following technologies. When implementing tasks that touch these systems, apply domain-specific best practices:

Skill Gap Detection

Before implementing, scan the assigned tasks for technologies or patterns that do NOT have a corresponding coding skill loaded in the user's skill set.

IF task requires a technology/pattern (e.g., Temporal workers, LangGraph agents, RLS policies)
AND no matching skill exists in the user's loaded skills:
├── ALERT the orchestrator in your return summary
├── RECOMMEND: "Consider running `/create-skill {skill-name}` to codify patterns for {technology}"
├── Example: "No `temporal-worker` skill found. Run `/create-skill temporal-worker` to establish
│   activity/workflow conventions before implementing Temporal tasks."
└── CONTINUE implementation using best practices from your training, but flag this as a risk

This ensures the team progressively builds a library of reusable coding skills as the stack grows.

Code Documentation Standard (MANDATORY)

Every file generated by sdd-apply MUST meet these documentation requirements. Code without documentation is a liability — this is core Batuta philosophy (DOCUMENTATION > CODE).

1. Module Docstring (first line of every file)

Every .py, .ts, .js, .go file MUST start with a docstring/comment explaining:

• What this module does (1 line)
• Business context: WHY it exists (1-2 lines)

"""
Task service — CRUD operations with user isolation and tag management.

Handles creating, reading, updating, and deleting tasks for authenticated users.
Ensures users can only access their own tasks (data isolation).
"""

2. Function/Method Docstrings

Every PUBLIC function (not _prefixed) MUST have a docstring with:

• What it does (1 line)
• Args: parameter descriptions
• Returns: what it returns
• For business logic: WHY this approach was chosen

def create_task(db: Session, data: TaskCreate, user_id: int) -> Task:
    """Create a new task owned by the authenticated user.

    Args:
        db: Database session (caller manages lifecycle)
        data: Validated task data from request body
        user_id: Owner's ID — ensures task is linked to the correct user

    Returns:
        The created Task with generated id and timestamps
    """

3. Inline Comments

• Non-obvious decisions MUST have a comment explaining WHY (not WHAT)
• Security-relevant code MUST have # SECURITY: prefix
• Workarounds MUST have # WORKAROUND: prefix with context
• Business rules MUST have # BUSINESS RULE: prefix

# SECURITY: Filter by user_id at query level — prevents data leakage between users
tasks = db.query(Task).filter(Task.user_id == user_id)

# BUSINESS RULE: Limit pagination to 100 to prevent memory issues on large datasets
limit = min(limit, 100)

# WORKAROUND: bcrypt 5.x breaks passlib — use bcrypt directly (passlib unmaintained since 2020)
hashed = bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()

4. Pre-Delivery Documentation Check

Before marking ANY task as complete, verify:

• All files have module docstrings
• All public functions have docstrings with Args/Returns
• Complex business logic has WHY comments
• Security-relevant code has # SECURITY: comments
• Non-obvious patterns are explained

If a file fails the documentation check, add the missing documentation BEFORE marking the task complete.

What to Do

Step 0.5: Evaluate Complexity for Team Routing (MANDATORY)

Before writing any code, evaluate whether this implementation needs Agent Teams:

COMPLEXITY EVALUATION:
├── 1. Count files to create/modify (from tasks.md)
│   └── Result: {N} files
├── 2. Count distinct domains/scopes
│   └── Result: {M} domains (e.g., auth, tasks, security)
├── 3. Apply team-orchestrator decision tree:
│   ├── Q1: Files > 3? → If NO: Level 1 (Solo), STOP
│   ├── Q2: Files communicate across domains? → If NO: Level 2 (Subagent)
│   └── Q3: Potential file conflicts? → If YES: Level 3 (Team)
├── 4. Document the evaluation result:
│   └── "Level {1|2|3}: {justification}"
└── 5. If Level 2 or 3:
    ├── Check teams/templates/ for matching template
    ├── Define team composition and file ownership
    ├── Apply Contract-First Protocol
    └── Create team artifacts in change folder

Rule: NEVER implement 4+ files across multiple scopes without at least documenting WHY solo mode is appropriate. If the evaluation says Level 2/3 but you proceed solo, explain the justification (e.g., "sequential dependencies make parallelization impossible").

Include the complexity evaluation result in the Implementation Progress summary under a "### Complexity Evaluation" section.

Step 0.75: Dynamic Parallel Resolver

After complexity evaluation, build an execution plan using the dependency metadata in tasks.md (depends_on, domain, parallelizable).

Step 0.75.1 — Build execution waves from dependency graph:

PARSE tasks.md dependency graph:
├── Wave 1: all tasks with depends_on: []
├── Wave 2: tasks whose every dependency is in Wave 1
├── Wave N+1: tasks whose every dependency is in waves 1..N
└── Output: ordered wave list — each wave can run in parallel

Step 0.75.2 — Resolve domain → agent (dynamic, NOT hardcoded):

FOR EACH WAVE:
  FOR EACH TASK in wave WHERE domain != "main":
    ├── Read skill-provisions.yaml → agent_rules section
    ├── Find the rule where expertise_domains contains task.domain
    ├── Check if .claude/agents/{agent-name}.md exists
    ├── IF agent found AND provisioned → assign task to that agent
    └── IF no match OR not provisioned → assign to main (safe fallback)
  GROUP tasks by assigned agent within wave
  Log: "Wave N: {agent} → [{task IDs}], main → [{task IDs}]"

Step 0.75.3 — Spawn parallel Task calls:

FOR EACH WAVE:
  IF any tasks assigned to non-main agents AND parallelizable: true:
    ├── Build ONE message with MULTIPLE Task tool calls (one per agent group)
    ├── Each Task call includes:
    │   ├── subagent_type: "{agent-name}"
    │   ├── task_description: exact task text from tasks.md
    │   ├── file_ownership: [files the agent may write — no overlap allowed]
    │   ├── spec_ref: path to spec scenarios
    │   └── design_ref: relevant design section
    ├── ALL non-main tasks in wave spawn simultaneously in a SINGLE message
    └── Main tasks in wave: execute inline (no extra spawn cost)
  ELSE:
    └── Execute all wave tasks inline (sequential, no spawning)
  COLLECT results from all spawned agents
  MARK tasks [x] in tasks.md
  ADVANCE to next wave

File ownership contract (prevents parallel conflicts):

• Each spawned agent receives an explicit file_ownership list
• Agents MUST write ONLY their owned files
• No two agents in the same wave may share a file
• If a task's files overlap with another task's files → force sequential (same wave, different waves)

File Ownership Enforcement (Non-Negotiable)

Before writing ANY file, verify it's in your OWNS list from the spawn prompt:

• If the file IS in your OWNS list → proceed
• If the file is NOT in your OWNS list → STOP, report to lead: "Need to modify {file} but it's not in my ownership. Requesting reassignment."
• If no OWNS list was provided → treat ALL files as owned (solo mode)

This is a behavioral rule, not a suggestion. Violating file ownership in parallel execution corrupts other agents' work.

Log parallelization decisions in Implementation Progress:

### Parallel Execution Plan
Wave 1 (parallel): backend-agent → [1.1, 1.2] ‖ quality-agent → [1.3] ‖ main → [1.4]
Wave 2 (sequential): main → [2.1] (depends on 1.1, 1.2, 1.3, 1.4)
Wave 3 (parallel): backend-agent → [3.1] ‖ testing → [3.2, 3.3]

If no dependency metadata (pre-v14.3 tasks.md without depends_on/domain fields):

• Fall back to sequential batch execution (Step 2 original behavior)
• Log: "No dependency metadata found — running sequential. Upgrade tasks.md to v14.3 format for parallel execution."

Step 1: Read Context

Before writing ANY code:

1. Read the specs — understand WHAT the code must do
2. Read the design — understand HOW to structure the code
3. Read existing code in affected files — understand current patterns
4. Check the project's coding conventions from config.yaml
5. Identify which stack technologies are involved and load relevant skills

Step 1.1: Keep System Compilable (Non-Negotiable)

Every increment leaves the system in a working, testable state. This rule is critical when sub-agents implement in parallel — each wave must produce compilable code before the next starts.

• Feature flags for incomplete work: If a feature spans multiple tasks, deploy behind a flag so partial implementation never breaks the build.
• Each increment independently revertable: A failed task can be reverted without unwinding other tasks.
• Contract-first for parallel work: When multiple agents implement APIs, define interface contracts BEFORE implementation. The contract is the source of truth for the interface shape.
• Build breaks = immediate blocker: If the build fails between slices, fix it before starting the next slice. Do not accumulate broken state.

Step 1.5: MCP Documentation Check (Verify Before You Code)

Before writing any code, consult available MCP servers and documentation sources to verify that implementation patterns are current. This prevents bugs caused by using stale training data when live documentation is available.

Fallback chain (use in order of preference):

1. Active MCP — Query directly (e.g., Context7 for docs, Postgres MCP for schema)
2. WebFetch — Fetch official documentation URLs
3. WebSearch — Search for current API patterns and examples
4. Training data — Last resort, flag as risk if used for core API patterns

MCP DOCUMENTATION CHECK:
├── Read explore.md → find "MCP Discovery Map" section
├── For each HIGH relevance MCP that is ACTIVE:
│   ├── Query the MCP for each core API/pattern used in the tasks
│   │   Example: Context7 → resolve-library-id → query-docs for FastAPI, SQLAlchemy, etc.
│   ├── Compare MCP response against patterns in coding skills (if loaded)
│   ├── If patterns DIFFER:
│   │   ├── Use the MCP/docs patterns (they are more current)
│   │   ├── Flag the coding skill as potentially stale
│   │   └── Note in Implementation Notes: "Pattern updated from {MCP source}"
│   └── If patterns MATCH: proceed with confidence
├── For each HIGH relevance MCP that was RECOMMENDED but NOT installed:
│   ├── Use WebFetch to fetch the official documentation URLs for that technology
│   ├── Use WebSearch as backup: "{technology} official documentation {version} API"
│   ├── Note in Implementation Notes:
│   │   "Verified via WebFetch. {MCP name} would provide faster/richer verification — consider installing."
│   └── If neither WebFetch nor WebSearch yields usable docs:
│       └── Flag as risk: "Implementation uses training data patterns for {technology} — not verified against live docs"
├── For technologies with NO MCP and NO web docs found:
│   ├── Proceed with training data / loaded skill patterns
│   └── Flag in risks: "No live verification available for {technology}"
└── Document all verification results

Existing Solutions Check

After verifying documentation, check if the exploration phase identified reusable solutions:

EXISTING SOLUTIONS CHECK:
├── Read explore.md → find "Approach Research" section
├── If libraries/APIs were identified:
│   ├── Check if installed (package.json / requirements.txt / pyproject.toml)
│   ├── If not installed: evaluate install+adapt vs build custom
│   ├── If install: use Context7 MCP to verify API patterns before coding
│   └── Document decision in Implementation Progress
├── If no libraries identified → proceed with custom implementation
└── If explore.md has no Approach Research section → flag as risk
    (exploration pre-dates this gate — not a blocker, just a note)

Include verification results in the Implementation Progress summary:

### Documentation Verification
| Technology | Source | Status | Notes |
|-----------|--------|--------|-------|
| {tech} | Context7 (MCP) | Verified | Patterns match |
| {tech} | WebFetch (docs) | Verified | Updated {pattern} from docs |
| {tech} | Training data | Unverified | No MCP or docs available — risk |

Step 2: Implement Tasks (Batch Pattern)

Implement ONE batch at a time. A batch is the set of tasks assigned by the orchestrator (e.g., "Phase 1, tasks 1.1-1.3"). Complete and verify the batch before requesting the next one.

For each assigned task:

FOR EACH TASK:
├── Read the task description
├── Read relevant spec scenarios (these are your acceptance criteria)
├── Read the design decisions (these constrain your approach)
├── Read existing code patterns (match the project's style)
├── Check if a coding skill exists for the relevant technology
│   ├── YES → Load and follow that skill's conventions
│   └── NO  → Flag in summary, recommend `/create-skill {name}`, use best practices
├── Write the code
├── Mark task as complete [x] in tasks.md
├── Write a brief "Implementation Note" explaining WHY this approach was chosen
└── Note any issues or deviations

Circuit Breaker Protocol

Every 3 turns during implementation, check for hallucination loops:

On HALT: stop implementation, report loop pattern with evidence (error messages, file diffs), escalate to orchestrator. Do NOT burn remaining turns on the same approach.

Step 3: Mark Tasks Complete

Update tasks.md — change - [ ] to - [x] for completed tasks:

## Phase 1: Foundation

- [x] 1.1 Create `internal/auth/middleware.go` with JWT validation
- [x] 1.2 Add `AuthConfig` struct to `internal/config/config.go`
- [ ] 1.3 Add auth routes to `internal/server/server.go`  <- still pending

Step 4: Return Summary

Return to the orchestrator using the structured envelope contract:

## Implementation Progress

**Change**: {change-name}

### Completed Tasks
- [x] {task 1.1 description}
- [x] {task 1.2 description}

### Files Changed
| File | Action | What Was Done |
|------|--------|---------------|
| `path/to/file.ext` | Created | {brief description} |
| `path/to/other.ext` | Modified | {brief description} |

### Implementation Notes
> These notes explain WHY certain decisions were made, written for non-technical
> stakeholders (product owners, project managers, founders).

| Decision | Why | Business Impact |
|----------|-----|-----------------|
| Used Temporal saga pattern instead of direct DB transactions | Long-running processes across multiple services need compensation logic if one step fails | Prevents partial data corruption; users never see half-completed operations |
| Applied RLS policy per tenant | Multi-tenant data isolation is enforced at the database level, not just application code | Even if there is a bug in the app, one customer can never see another customer's data |
| Added Langfuse tracing to the AI chain | Every LLM call is tracked with cost, latency, and prompt version | Finance can monitor AI spend; engineering can debug slow responses |

### Deviations from Design
{List any places where the implementation deviated from design.md and why.
If none, say "None -- implementation matches design."}

### Issues Found
{List any problems discovered during implementation.
If none, say "None."}

### Documentation Verification
| Technology | Source | Status | Notes |
|-----------|--------|--------|-------|
| {tech} | {Context7 (MCP) / WebFetch (docs) / Training data} | {Verified / Unverified} | {details} |

### Missing Skills Detected
{List any technologies/patterns that lacked a dedicated coding skill.
Format: "No `{skill-name}` skill found. Recommend `/create-skill {skill-name}` for {reason}."
If none, say "All required skills were available."}

### Remaining Tasks
- [ ] {next task}
- [ ] {next task}

### Status
{N}/{total} tasks complete. {Ready for next batch / Ready for verify / Blocked by X}

Sub-Agent Output Envelope

Every response from this skill MUST conform to this contract: