Coding Playbook

Milestone guidelines for coding teams:

• 25%: Design complete, approach planned
• 50%: Implementation complete, code written
• 75%: Tests passing, ready to open PR
• 100%: PR opened, ready for review

Also write progress signals to outbox:

Write a JSON file to .squad/signals/outbox/ for meta relay to pick up:

echo '{"type":"progress","from":"{domain}","subject":"implementation_done","body":"Implemented feature in 3 files","metadata":{"percent":50}}' > .squad/signals/outbox/$(date +%s)-progress-impl.json

Important: Only report major milestones. Don't spam with every file read.

Phase 1: Design

Read your task

Start by reading DOMAIN_CONTEXT.md in your working directory. This file describes your domain, your responsibilities, and the current task. If it references external specs or design documents, check .squad/signals/inbox/ — the meta-squad or other teams may have placed detailed specifications, architecture decisions, or interface contracts there.

Understand the requirements

Before writing a single line of code, answer these questions:

• What is the expected behavior when this task is complete?
• What inputs does this feature accept? What outputs does it produce?
• What existing code does this change touch? What are the boundaries?
• Are there constraints — performance, compatibility, security — that affect the design?

If any of these answers are unclear, make reasonable assumptions and document them. You are operating in headless mode — you do not ask questions. You decide, document, and move forward.

Plan the approach

Write a brief design note — either in a comment at the top of the primary file you will change, or in your status signal. Include:

• Which files you will create or modify.
• The key abstractions or data structures involved.
• Any dependencies on other teams or external services.
• Edge cases you have identified.

Check for prior art

Before designing from scratch, look at the existing codebase:

• Are there similar features already implemented? Follow their patterns.
• Is there a style guide, linting configuration, or code convention document?
• Are there utility functions or shared libraries that solve part of your problem?

Write what you discover to .squad/learnings/log.jsonl so future runs benefit from your investigation.

Knowledge: Log discoveries as type "pattern" or "technique". "Authentication in this codebase uses middleware pattern in src/middleware/auth.ts." "All database queries follow repository pattern — see src/repos/ for examples."

Update status

Write to .squad/signals/status.json:

{
  "state": "working",
  "step": "design",
  "summary": "Analyzed requirements. Planning implementation of [brief description].",
  "timestamp": "<ISO-8601>"
}

Phase 2: Implement

Follow project conventions

Match the existing codebase style. If the project uses tabs, use tabs. If functions are camelCase, follow camelCase. If there is an .editorconfig, .eslintrc, pyproject.toml, or similar configuration, respect it.

Do not introduce new dependencies unless the task explicitly requires them. If you must add a dependency, document why.

Write clean, reviewable code

Your code will be reviewed by humans or other agents. Optimize for clarity:

• Small, focused functions with descriptive names.
• Meaningful variable names — avoid abbreviations unless they are domain-standard.
• Comments only where the code cannot speak for itself. Explain why, not what.
• Group related changes into logical commits when possible.

Handle errors and edge cases

Do not write only the happy path. Consider:

• What happens with empty inputs, null values, or missing configuration?
• What happens when an external service is unreachable?
• What happens when data is malformed or out of expected range?

Fail explicitly with clear error messages rather than silently producing wrong results.

Incremental progress

If the task is large, break it into smaller steps. Complete each step fully — working code, no half-implemented features. If you cannot finish everything, deliver what is complete and document what remains in your outbox signal.

Write learnings as you go

As you navigate the codebase, record what you learn in .squad/learnings/log.jsonl:

{"ts": "<ISO-8601>", "type": "pattern", "agent": "your-name", "domain": "generalizable", "tags": ["auth"], "title": "Authentication middleware pattern", "body": "All protected routes use withAuth() wrapper from src/middleware/auth.ts", "confidence": "high"}
{"ts": "<ISO-8601>", "type": "technique", "agent": "your-name", "domain": "generalizable", "tags": ["database"], "title": "Repository pattern for DB queries", "body": "Database queries use the repository pattern — see src/repos/ for examples. Each entity has a dedicated repository class.", "confidence": "high"}
{"ts": "<ISO-8601>", "type": "gotcha", "agent": "your-name", "domain": "local", "tags": ["config"], "title": "Config loader caches at import time", "body": "The config loader caches values at import time — changing env vars after startup has no effect. Must restart to pick up config changes.", "confidence": "high"}

These entries help you on future runs and help other teams understand the codebase.

Knowledge: Log immediately when you discover something. Don't wait until the end. Pattern = reusable approach. Technique = how-to. Gotcha = trap to avoid.

Update status

{
  "state": "working",
  "step": "implement",
  "summary": "Implementing [brief description]. Modified [N] files so far.",
  "timestamp": "<ISO-8601>"
}

Phase 3: Test

Write tests for your changes

Every code change must have corresponding tests. Match the project's existing test framework and conventions:

• Unit tests for individual functions and methods.
• Integration tests for workflows that cross module boundaries.
• Edge case tests for the failure modes you identified during design.

If the project has no existing test infrastructure, create a minimal test file that exercises your changes. Document in your PR description that test infrastructure was bootstrapped.

Run existing tests

Before opening a PR, run the full test suite (or the relevant subset) to confirm you have not broken existing functionality. If tests fail:

• If the failure is caused by your changes, fix it.
• If the failure is pre-existing and unrelated, document it in your PR description.

Verify manually

When possible, exercise your changes end-to-end. If you built an API endpoint, call it. If you built a CLI command, run it. If you built a data transformation, feed it sample input.

Update status

{
  "state": "working",
  "step": "test",
  "summary": "Tests written and passing. [N] new tests added. Full suite passing.",
  "timestamp": "<ISO-8601>"
}

Phase 4: PR

Open a pull request

Create a pull request with:

• Title: A concise description of what changed and why.
• Description: Explain the problem, the approach, and any decisions you made. Link to the task or spec if one exists.
• Changes: List the files modified and what each change does at a high level.
• Testing: Describe what tests you added and how to verify the changes.
• Assumptions: Document any assumptions you made during headless execution.

Keep PRs focused

One PR per logical change. If your task requires multiple independent changes, open multiple PRs. Reviewers should be able to understand and approve each PR independently.

Write a completion signal

Write to .squad/signals/outbox/:

{
  "type": "pr_opened",
  "summary": "Opened PR #[N]: [title]",
  "pr_url": "[URL]",
  "files_changed": ["list", "of", "files"],
  "tests_added": ["list", "of", "test", "files"],
  "timestamp": "<ISO-8601>"
}

Knowledge: After completing your PR, update .squad/agents/*/history.md with what this implementation taught you. Update .squad/decisions.md with significant technical choices you made. If patterns emerged that will apply to future work, capture them in .squad/identity/wisdom.md.

Update status

{
  "state": "complete",
  "step": "pr",
  "summary": "PR opened: [title]. Ready for review.",
  "timestamp": "<ISO-8601>"
}

Signal Protocol

Throughout your work, maintain communication through the signal system:

• Status (.squad/signals/status.json): Update after each step transition. Always include state, step, summary, and timestamp. Use canonical state values: initializing, working, complete, failed, paused.
• Inbox (.squad/signals/inbox/): Check at the start of each phase. The meta-squad or other teams may send you feedback, updated requirements, or priority changes.
• Outbox (.squad/signals/outbox/): Write completion reports, blockers, and questions. If you are blocked on something you cannot resolve, write it here — do not stop working on what you can do.
• Learnings (.squad/learnings/log.jsonl): Write codebase discoveries, patterns, and gotchas as you encounter them.

Handling Feedback

If you find code review comments or feedback in your inbox:

1. Read all feedback before making changes.
2. Address each comment — fix the code, or document why you disagree.
3. Update your PR with the fixes.
4. Write a response summary to your outbox.

Knowledge: Code review feedback is valuable learning. Log feedback-driven corrections to .squad/learnings/log.jsonl as type "correction". "Reviewer taught us that approach X is preferred because Y." Update wisdom when feedback reveals deeper code quality principles. If a review-validated pattern proves repeatable, extract it as a skill.

Headless Execution

You operate without human interaction. When you face ambiguity:

• Choose the simpler approach.
• Follow existing patterns in the codebase.
• Document your assumptions clearly.
• Prefer reversible decisions over irreversible ones.

Never stop and wait for input. Always move forward.