0xhoneyjar/.claude/skills/implementing-tasks

Sprint Task Implementer

<objective> Implement sprint tasks from `loa-grimoire/sprint.md` with production-grade code and comprehensive tests. Generate detailed implementation report at `loa-grimoire/a2a/sprint-N/reviewer.md`. Address feedback iteratively until senior lead and security auditor approve. </objective>

<zone_constraints>

Zone Constraints

This skill operates under Managed Scaffolding:

| Zone | Permission | Notes | |------|------------|-------| | .claude/ | NONE | System zone - never suggest edits | | loa-grimoire/, .beads/ | Read/Write | State zone - project memory | | src/, lib/, app/ | Read-only | App zone - requires user confirmation |

NEVER suggest modifications to .claude/. Direct users to .claude/overrides/ or .loa.config.yaml. </zone_constraints>

<integrity_precheck>

Integrity Pre-Check (MANDATORY)

Before ANY operation, verify System Zone integrity:

1. Check config: yq eval '.integrity_enforcement' .loa.config.yaml
2. If strict and drift detected -> HALT and report
3. If warn -> Log warning and proceed with caution </integrity_precheck>

<factual_grounding>

Factual Grounding (MANDATORY)

Before ANY synthesis, planning, or recommendation:

1. Extract quotes: Pull word-for-word text from source files
2. Cite explicitly: "[exact quote]" (file.md:L45)
3. Flag assumptions: Prefix ungrounded claims with [ASSUMPTION]

Grounded Example:

The SDD specifies "PostgreSQL 15 with pgvector extension" (sdd.md:L123)

Ungrounded Example:

[ASSUMPTION] The database likely needs connection pooling

</factual_grounding>

<structured_memory_protocol>

Structured Memory Protocol

On Session Start

1. Read loa-grimoire/NOTES.md
2. Restore context from "Session Continuity" section
3. Check for resolved blockers

During Execution

1. Log decisions to "Decision Log"
2. Add discovered issues to "Technical Debt"
3. Update sub-goal status
4. Apply Tool Result Clearing after each tool-heavy operation

Before Compaction / Session End

1. Summarize session in "Session Continuity"
2. Ensure all blockers documented
3. Verify all raw tool outputs have been decayed </structured_memory_protocol>

<tool_result_clearing>

Tool Result Clearing

After tool-heavy operations (grep, cat, tree, API calls):

1. Synthesize: Extract key info to NOTES.md or discovery/
2. Summarize: Replace raw output with one-line summary
3. Clear: Release raw data from active reasoning

Example:

# Raw grep: 500 tokens -> After decay: 30 tokens
"Found 47 AuthService refs across 12 files. Key locations in NOTES.md."

</tool_result_clearing>

<trajectory_logging>

Trajectory Logging

Log each significant step to loa-grimoire/a2a/trajectory/{agent}-{date}.jsonl:

{"timestamp": "...", "agent": "...", "action": "...", "reasoning": "...", "grounding": {...}}

</trajectory_logging>

<kernel_framework>

Task (N - Narrow Scope)

Implement sprint tasks from loa-grimoire/sprint.md with production-grade code and tests. Generate implementation report at loa-grimoire/a2a/sprint-N/reviewer.md. Address feedback iteratively.

Context (L - Logical Structure)

• Input: loa-grimoire/sprint.md (tasks), loa-grimoire/prd.md (requirements), loa-grimoire/sdd.md (architecture)
• Feedback loops:
  • loa-grimoire/a2a/sprint-N/auditor-sprint-feedback.md (security audit - HIGHEST PRIORITY)
  • loa-grimoire/a2a/sprint-N/engineer-feedback.md (senior lead review)
• Integration context: loa-grimoire/a2a/integration-context.md (if exists) for context preservation, documentation locations, commit formats
• Current state: Sprint plan with acceptance criteria
• Desired state: Working, tested implementation + comprehensive report

Constraints (E - Explicit)

• DO NOT start new work without checking for audit feedback FIRST (highest priority)
• DO NOT start new work without checking for engineer feedback SECOND
• DO NOT assume feedback meaning—ask clarifying questions if unclear
• DO NOT skip tests—comprehensive test coverage is non-negotiable
• DO NOT ignore existing codebase patterns—follow established conventions
• DO NOT skip reading context files—always review PRD, SDD, sprint.md
• DO link implementations to source discussions if integration context requires
• DO update relevant documentation if specified in integration context
• DO format commits per org standards if defined
• DO follow SemVer for version updates

Verification (E - Easy to Verify)

Success = All acceptance criteria met + comprehensive tests pass + detailed report at expected path

Report MUST include:

• Executive Summary
• Tasks Completed (files/lines modified, approach, test coverage)
• Technical Highlights (architecture, performance, security, integrations)
• Testing Summary (test files, scenarios, how to run)
• Known Limitations
• Verification Steps for reviewer
• Feedback Addressed section (if iteration after feedback)

Reproducibility (R - Reproducible Results)

• Write tests with specific assertions: NOT "it works" → "returns 200 status, response includes user.id field"
• Document specific file paths and line numbers: NOT "updated auth" → "src/auth/middleware.ts:42-67"
• Include exact commands to reproduce: NOT "run tests" → "npm test -- --coverage --watch=false"
• Reference specific commits or branches when relevant </kernel_framework>

<uncertainty_protocol>

• If requirements are ambiguous, reference PRD and SDD for clarification
• If feedback is unclear, ASK specific clarifying questions before proceeding
• Say "I need clarification on [X]" when feedback meaning is uncertain
• Document interpretations and reasoning in report for reviewer attention
• Flag technical tradeoffs explicitly for reviewer decision </uncertainty_protocol>

<grounding_requirements> Before implementing:

1. Check loa-grimoire/a2a/sprint-N/auditor-sprint-feedback.md FIRST (security audit)
2. Check loa-grimoire/a2a/sprint-N/engineer-feedback.md SECOND (senior lead)
3. Check loa-grimoire/a2a/integration-context.md for organizational context
4. Read loa-grimoire/sprint.md for acceptance criteria
5. Read loa-grimoire/sdd.md for technical architecture
6. Read loa-grimoire/prd.md for business requirements
7. Quote requirements when implementing: > From sprint.md: Task 1.2 requires... </grounding_requirements>

<citation_requirements>

• Reference sprint task IDs when implementing
• Cite SDD sections for architectural decisions
• Include file paths and line numbers in report
• Quote feedback items when addressing them
• Reference test file paths and coverage metrics </citation_requirements>

<workflow> ## Phase -2: Beads Integration Check

Check if Beads is available for task lifecycle management:

.claude/scripts/check-beads.sh --quiet

If INSTALLED, use Beads for task lifecycle:

• bd ready - Get next actionable task (JIT retrieval)
• bd update <task-id> --status in_progress - Mark task started (done automatically)
• bd close <task-id> - Mark task completed (done automatically)
• Task state persists across context windows

If NOT_INSTALLED, use markdown-based tracking from sprint.md.

IMPORTANT: Users should NOT run bd commands manually. This agent handles the entire Beads lifecycle internally:

1. On start: Run bd ready to find first unblocked task
2. Before implementing: Auto-run bd update <task-id> --status in_progress
3. After completing: Auto-run bd close <task-id>
4. Repeat until sprint complete

Phase -1: Context Assessment & Parallel Task Splitting (CRITICAL—DO THIS FIRST)

Assess context size to determine if parallel splitting is needed:

wc -l loa-grimoire/prd.md loa-grimoire/sdd.md loa-grimoire/sprint.md loa-grimoire/a2a/*.md 2>/dev/null

Thresholds: | Size | Lines | Strategy | |------|-------|----------| | SMALL | <3,000 | Sequential implementation | | MEDIUM | 3,000-8,000 | Consider parallel if >3 independent tasks | | LARGE | >8,000 | MUST split into parallel |

If MEDIUM/LARGE: See <parallel_execution> section below.

If SMALL: Proceed to Phase 0.

Phase 0: Check Feedback Files and Integration Context (BEFORE NEW WORK)

Step 1: Security Audit Feedback (HIGHEST PRIORITY)

Check loa-grimoire/a2a/sprint-N/auditor-sprint-feedback.md:

If exists + "CHANGES_REQUIRED":

• Sprint FAILED security audit
• MUST address ALL CRITICAL and HIGH priority security issues
• Address MEDIUM and LOW if feasible
• Update report with "Security Audit Feedback Addressed" section
• Quote each audit issue with your fix and verification steps

If exists + "APPROVED - LETS FUCKING GO":

• Sprint passed security audit
• Proceed to check engineer feedback

If missing:

• No security audit yet
• Proceed to check engineer feedback

Step 2: Senior Lead Feedback

Check loa-grimoire/a2a/sprint-N/engineer-feedback.md:

If exists + NOT "All good":

• Senior lead requested changes
• Address all feedback items systematically
• Update report with "Feedback Addressed" section

If exists + "All good":

• Sprint approved by senior lead
• Proceed with new work or wait for security audit

If missing:

• First implementation
• Proceed with implementing sprint tasks

Step 3: Integration Context

Check loa-grimoire/a2a/integration-context.md:

If exists, read for:

• Context preservation requirements (link to source discussions)
• Documentation locations (where to update status)
• Commit message formats (e.g., "[LIN-123] Description")
• Available MCP tools

Phase 1: Context Gathering and Planning

1. Review core documentation:

   • loa-grimoire/sprint.md - Primary task list and acceptance criteria
   • loa-grimoire/prd.md - Product requirements and business context
   • loa-grimoire/sdd.md - System design and technical architecture

2. Analyze existing codebase:

   • Understand current architecture and patterns
   • Identify existing components to integrate with
   • Note coding standards and conventions
   • Review existing test patterns

3. Create implementation strategy:

   • Break down tasks into logical order
   • Identify task dependencies
   • Plan test coverage for each component

Phase 2: Implementation

Beads Task Loop (if Beads installed)

# 1. Get next actionable task
TASK=$(bd ready --format json | head -1)
TASK_ID=$(echo $TASK | jq -r '.id')

# 2. Mark in progress (automatic - user never sees this)
bd update $TASK_ID --status in_progress

# 3. Implement the task...

# 4. Mark complete (automatic - user never sees this)
bd close $TASK_ID

# 5. Repeat for next task

The user only runs /implement sprint-1. All bd commands are invisible.

For each task:

1. Implement according to specifications
2. Follow established project patterns
3. Write clean, maintainable, documented code
4. Consider performance, security, scalability
5. Handle edge cases and errors gracefully

Testing Requirements:

• Comprehensive unit tests for all new code
• Test both happy paths and error conditions
• Include edge cases and boundary conditions
• Follow existing test patterns
• Ensure tests are readable and maintainable

Code Quality Standards:

• Self-documenting with clear names
• Comments for complex logic
• DRY principles
• Consistent formatting
• Future maintainability

Phase 3: Documentation and Reporting

Create report at loa-grimoire/a2a/sprint-N/reviewer.md:

Use template from resources/templates/implementation-report.md.

Key sections:

• Executive Summary
• Tasks Completed (with files, approach, tests)
• Technical Highlights
• Testing Summary
• Known Limitations
• Verification Steps

Phase 4: Feedback Integration Loop

1. Monitor for feedback files
2. When feedback received:
   • Read thoroughly
   • If unclear: ask specific clarifying questions
   • Never assume about vague feedback
3. Address feedback systematically
4. Generate updated report </workflow>

<parallel_execution>

When to Split

• SMALL (<3,000 lines): Sequential
• MEDIUM (3,000-8,000 lines) with >3 independent tasks: Consider parallel
• LARGE (>8,000 lines): MUST split

Option A: Parallel Feedback Checking (Phase 0)

When multiple feedback sources exist:

Spawn 2 parallel Explore agents:

Agent 1: "Read loa-grimoire/a2a/sprint-N/auditor-sprint-feedback.md:
1. Does file exist?
2. If yes, verdict (CHANGES_REQUIRED or APPROVED)?
3. If CHANGES_REQUIRED, list all CRITICAL/HIGH issues with file paths
Return: structured summary"

Agent 2: "Read loa-grimoire/a2a/sprint-N/engineer-feedback.md:
1. Does file exist?
2. If yes, verdict (All good or changes requested)?
3. If changes, list all feedback items with file paths
Return: structured summary"

Option B: Parallel Task Implementation (Phase 2)

When sprint has multiple independent tasks:

1. Read sprint.md and identify all tasks
2. Analyze task dependencies
3. Group into parallel batches:
   - Batch 1: Tasks with no dependencies (parallel)
   - Batch 2: Tasks depending on Batch 1 (after Batch 1)

For independent tasks, spawn parallel agents:
Agent 1: "Implement Task 1.2 - read acceptance criteria, review patterns, implement, write tests, return summary"
Agent 2: "Implement Task 1.3 - read acceptance criteria, review patterns, implement, write tests, return summary"

Consolidation

1. Collect results from all parallel agents
2. Verify no conflicts between implementations
3. Run integration tests across all changes
4. Generate unified report </parallel_execution>

<output_format> See resources/templates/implementation-report.md for full structure.

Key sections:

• Executive Summary
• Tasks Completed (files, approach, tests)
• Technical Highlights
• Testing Summary
• Known Limitations
• Verification Steps
• Feedback Addressed (if iteration) </output_format>

<success_criteria>

• Specific: Every task implemented per acceptance criteria
• Measurable: Test coverage metrics included
• Achievable: All sprint tasks completed
• Relevant: Implementation matches PRD/SDD
• Time-bound: Report generated for review </success_criteria>

<semver_requirements>

Version Format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes (incompatible API changes)
• MINOR: New features (backwards-compatible additions)
• PATCH: Bug fixes (backwards-compatible fixes)

When to Update Version

| Change | Bump | Example | |--------|------|---------| | New feature implementation | MINOR | 0.1.0 → 0.2.0 | | Bug fix | PATCH | 0.2.0 → 0.2.1 | | Breaking API change | MAJOR | 0.2.1 → 1.0.0 |

Version Update Process

1. Determine bump type based on changes
2. Update package.json version
3. Update CHANGELOG.md with sections: Added, Changed, Fixed, Removed, Security
4. Reference version in completion comments </semver_requirements>

<checklists> See `resources/REFERENCE.md` for complete checklists: - Pre-Implementation Checklist - Code Quality Checklist - Testing Checklist - Documentation Checklist - Versioning Checklist

Red Flags (immediate action required):

• No tests for new code
• Hardcoded secrets
• Skipped error handling
• Ignored existing patterns </checklists>