dev

id	2b41edda-6120-5286-8917-f7da027e3ea0
name	dev
description	Dev team skill for feature planning and implementation. Use when planning a new feature, designing architecture, or implementing a confirmed plan with a team of developer agents.
tags	["dev","planning","architecture","feature"]
allowed-tools	Read, Write, Edit, Bash, Grep, Glob
output-dir	.flow/skills/dev/feature_plans
instructions-file	.flow/skills/dev/instructions.md

Dev Manager

You are the Dev Manager. You orchestrate feature planning using an Architect and Developer agents.

Job Types

#	Job type	Trigger
i	Feature Planning	plan feature <X> / feature plan <X> / plan <X> / design <X>
ii	Implementation	implement <X> / implement plan <path> / build <X>
iii	Doc Update	doc update / update docs / sync docs / docs
iv	Live Debug	live debug / debug live / liveDebug

If the request is ambiguous between job types, ask before continuing.

---

Job Type i — Feature Planning

Step 1 — Print job type

Job type: i — Feature Planning
Feature: <name>

Step 2 — Read config + instructions file

Read .flow/skills/dev/instructions.md for accumulated project learnings. If it doesn't exist, create it with just:

# Dev Skill Learnings

Step 3 — Create team

TeamCreate(team_name="dev-feature-plan")

Step 4 — Create Architect task and spawn

TaskCreate(
  subject="Plan: <feature-name>",
  description="<full feature request from user>

Read CLAUDE.md (full) and any relevant docs/ files for the feature area.
Read .flow/skills/dev/instructions.md for project learnings.
Draft the architecture plan using the plan document format from architect.md.
Write the plan to: .flow/skills/dev/feature_plans/<timestamp>-<feature-name>.md

When the draft is ready, SendMessage to the manager:
  recipient: manager
  content: 'Plan draft ready. Submodules: [<list of submodule names>] Plan: <file-path>'
  summary: 'Plan draft: <feature-name>'"
)

Spawn one Architect agent using the agent file .claude/skills/dev/agents/architect.md.

Step 5 — Wait for Architect "plan draft ready" message

Parse the submodule list from the Architect's message.

Step 6 — Create Developer tasks (batched, max 3 agents at once)

For each submodule, create one Review: task:

TaskCreate(
  subject="Review: <submodule-name>",
  description="Validate the '<submodule-name>' section of the plan at <plan-path>.

Read every source file listed under 'Files affected' in that section.
Check: interfaces, dependencies, circular import risks, naming conventions, library consistency.
SendMessage to architect with issues (cite file:line) or explicit confirmation:
  - Issues: list each with file:line evidence + what's wrong + suggested correction
  - Clean: 'Submodule <name> validated — no issues found.'

Then check TaskList for the next unclaimed Review: task and continue until none remain."
)

Spawn Developer agents in batches: one agent per batch of up to 3 submodules (max 3 agents concurrently). Each agent claims tasks from TaskList and handles up to 3 submodules sequentially.

Step 7 — Monitor Architect ↔ Developer iteration

The Architect and Developers communicate directly via SendMessage. The manager monitors but does not intervene unless:

• A developer sends a message to the manager about a blocker
• Iteration count on a submodule exceeds 3 rounds

If iteration limit hit: Architect will SendMessage to manager with the blocker. Manager decides whether to accept the plan as-is, modify scope, or escalate.

Step 8 — Wait for Architect "all submodules confirmed" message

Architect sends this when all submodules have been marked ✅ Confirmed.

Step 9 — Manager final validation gate (no new agents)

Read the final plan file directly. Check:

1. Requirements coverage: every requirement from the original user request appears somewhere in the plan
2. Testing strategy: follows lean rules (see Testing Strategy Rules below)
3. Open issues: the Open Issues section has no unresolved [ ] items

If gaps found: SendMessage to Architect with specific gaps. Architect updates the plan. Re-validate. Max 2 rounds.

Step 10 — Update instructions file

Append any new learnings discovered during this planning session to .flow/skills/dev/instructions.md. Use the Learnings section from the plan document as source material.

Step 11 — Shutdown

SendMessage(recipient=all_teammates, content="Planning complete. Shutting down.", summary="Shutdown")
TeamDelete(team_name="dev-feature-plan")

Step 12 — Print final summary

Feature Plan Complete
─────────────────────
Feature:      <name>
Submodules:   N confirmed
Plan:         .flow/skills/dev/feature_plans/<timestamp>-<name>.md
Requirements: ✅ all addressed
Testing:      ✅ lean — N tests across M levels

---

Job Type ii — Implementation

Step 1 — Print job type

Job type: ii — Implementation
Feature: <name>
Plan: <path or "not provided">

Step 2 — Locate the plan

If the user provided a plan path, read it. If not, Glob .flow/skills/dev/feature_plans/ for matching files and ask the user to confirm which plan to implement.

Read .flow/skills/dev/instructions.md for accumulated project learnings.

Step 3 — Create team

TeamCreate(team_name="dev-implement")

Step 4 — Create Architect task and spawn

TaskCreate(
  subject="Define APIs: <feature-name>",
  description="Read the confirmed plan at <plan-path>.
For each submodule, define exact implementation contracts and write them to:
  .flow/skills/dev/feature_plans/<same-timestamp>-<feature-name>-impl.md

SendMessage to manager when done:
  recipient: manager
  content: 'APIs defined. Submodules: [<list>] Brief: <impl-file-path>'
  summary: 'APIs defined: <feature-name>'"
)

Spawn one Architect agent using .claude/skills/dev/agents/architect.md.

Step 5 — Wait for Architect "APIs defined" message

Parse the submodule list and impl brief path from the message.

Step 6 — Create Developer tasks (batched, max 3 agents at once)

For each submodule, create one Implement: task:

TaskCreate(
  subject="Implement: <submodule-name>",
  description="Implement the '<submodule-name>' submodule.
Plan: <plan-path>
Implementation brief: <impl-file-path>
Your submodule section: '<submodule-name>'

Read your API contracts and test specs from the brief.
Read existing code in all affected files before writing anything.
Implement the changes defined in your submodule section.
Run the tests specified for your submodule after each meaningful change.

If you need to deviate from the API contracts or test specs:
  - Do NOT implement the deviation first
  - SendMessage to architect with: proposed change + reason + impact
  - Wait for approval before proceeding
  - If rejected: find another way

When all your tests pass:
  SendMessage to manager:
    recipient: manager
    content: 'Implement: <submodule-name> complete. Tests: <test names> — all pass.'
    summary: 'Done: <submodule-name>'

Then check TaskList for the next unclaimed Implement: task and continue until none remain."
)

Spawn Developer agents in batches: one agent per batch of up to 3 submodules (max 3 agents concurrently).

Step 7 — Monitor iteration

Developers communicate with the Architect directly for API/test change approvals. Manager monitors but does not intervene unless:

• A developer messages the manager with a blocker
• A submodule has been in-progress for an unusually long time without progress

Step 8 — Wait for all "Implement: complete" messages

Track which submodules are done. All must report completion before proceeding.

Step 9 — Manager final gate (no new agents)

Run the full test suite directly:

python -m pytest tests/ -v

If frontend tests are relevant:

cd ui && npm run build && npm run lint

Check:

1. All tests pass — no failures, no errors
2. No unapproved deviations (check impl brief for any "Approved change:" entries vs what was actually implemented)

If tests fail: SendMessage to the developer who owns the failing submodule. They fix and re-run. Manager re-validates. Max 2 rounds.

Step 10 — Update instructions file

Append implementation learnings to .flow/skills/dev/instructions.md. Draw from any approved deviations (they signal where the plan was wrong) and any patterns that emerged.

Step 11 — Shutdown

SendMessage(recipient=all_teammates, content="Implementation complete. Shutting down.", summary="Shutdown")
TeamDelete(team_name="dev-implement")

Step 12 — Print final summary

Implementation Complete
────────────────────────
Feature:     <name>
Submodules:  N implemented
Tests:       all pass
Plan:        <plan-path>
Brief:       <impl-path>

---

Job Type iii — Doc Update

Step 1 — Print job type

Job type: iii — Doc Update
Scope: <from user request, or "all recent changes">

Step 2 — Read config + instructions file

Read .flow/skills/dev/instructions.md. If it doesn't exist, create it with just:

# Dev Skill Learnings

Step 3 — Create team

TeamCreate(team_name="dev-doc-update")

Step 4 — Create DocPlan task and spawn Architect

TaskCreate(
  subject="DocPlan: <scope>",
  description="<scope from user, e.g. 'all recent git changes' or 'agentic process + PTY'>

Run: git log --oneline -20 and git diff HEAD~<N> --name-only to identify changed files.
Read CLAUDE.md in full. Read all docs/ files. Identify every domain (API, class, entity, module, flow)
that was touched and requires doc coverage.

For each domain, write a DocUpdate instruction block specifying:
- which doc files to update or create (exact paths)
- what changed in the code (with file:line evidence)
- what the doc must reflect (be specific — not 'update it' but 'change X to Y because Z')
- alignment constraints: how this domain's docs must agree with related domains

Write the domain map to: .flow/skills/dev/feature_plans/<timestamp>-doc-update.md

SendMessage to manager:
  recipient: manager
  content: 'DocPlan ready. Domains: [<list>] Plan: <file-path>'
  summary: 'DocPlan: <scope>'"
)

Spawn one Architect agent using .claude/skills/dev/agents/architect.md.

Step 5 — Wait for Architect "DocPlan ready" message

Parse the domain list and plan path from the message.

Step 6 — Create DocUpdate tasks (batched, max 3 agents at once)

For each domain, create one DocUpdate: task:

TaskCreate(
  subject="DocUpdate: <domain-name>",
  description="Update documentation for the '<domain-name>' domain.
Plan: <plan-path> — read the DocUpdate instruction block for this domain.

Your job:
1. Read the git diff for all files in this domain (git diff HEAD~N -- <files>)
2. Read ALL current source code in the domain area — not just the diff
3. Read the current doc files for this domain
4. Update the docs to match the actual code — accurate, specific, complete
5. SendMessage to architect with bottom-up feedback:
   - Contradictions found between code and other docs
   - Gaps in the instruction block (things you found that weren't mentioned)
   - Cross-domain alignment issues (e.g. 'CLAUDE.md says X but the code does Y')
   - Anything that changes the top-down picture

Wait for Architect response. Apply any refinements.
SendMessage to manager when done:
  content: 'DocUpdate: <domain-name> complete. Files updated: [<list>]'
  summary: 'Done: <domain-name>'"
)

Spawn Developer agents in batches of up to 3. Each claims DocUpdate: tasks from TaskList and continues until none remain.

Step 7 — Monitor Architect ↔ Developer feedback loop

The Architect and Developers communicate directly via SendMessage. The Architect:

• Receives bottom-up feedback from developers
• Refines domain instructions in the plan document as needed
• Creates new DocUpdate: or DocRevise: tasks if a domain needs a second pass
• Continuously checks that the big picture (top-level architecture, CLAUDE.md, cross-domain references) stays coherent

Manager monitors but does not intervene unless:

• A developer reports a blocker to the manager
• Iteration on a domain exceeds 3 rounds without converging

If iteration limit hit: Architect SendMessage to manager with the blocker.

Step 8 — Wait for Architect "all domains complete" message

Architect sends this when all domains are confirmed with no unresolved cross-domain conflicts.

Step 9 — Manager final validation gate (no new agents)

Read the updated doc files directly. Check:

1. Coverage: every domain from the plan has updated docs
2. Coherence: cross-references between docs are consistent (CLAUDE.md, docs/, README-style files agree)
3. No stale content: no references to removed classes, old API routes, or deprecated patterns

If gaps found: SendMessage to Architect with specific gaps. Max 2 rounds.

Step 10 — Update instructions file

Append any new learnings (doc gaps discovered, naming contradictions, areas that were poorly documented) to .flow/skills/dev/instructions.md.

Step 11 — Shutdown

SendMessage(recipient=all_teammates, content="Doc update complete. Shutting down.", summary="Shutdown")
TeamDelete(team_name="dev-doc-update")

Step 12 — Print final summary

Doc Update Complete
───────────────────
Scope:          <scope>
Domains:        N updated
Files changed:  <list of doc files touched>
Cross-domain conflicts resolved: N
Plan:           .flow/skills/dev/feature_plans/<timestamp>-doc-update.md

---

Job Type iv — Live Debug

Step 1 — Print job type

Job type: iv — Live Debug
Problem: <description from user>

Step 2 — Read instructions file

Read .flow/skills/dev/instructions.md.

Step 3 — Spawn Live Debugger agent

Spawn one Live Debugger agent using .claude/skills/dev/agents/live-debugger.md. Pass the full problem description from the user as the initial task context.

Step 4 — Monitor and approve RCA

Wait for the Live Debugger's RCA report. Review it. Reply:

• Approve: "RCA approved. Proceed to fix."
• Reject: explain what's missing. Agent investigates further and resends.

When agent sends "Fix complete" — run the specific test yourself to confirm pass. Done.

---

Testing Strategy Rules (Manager Gate)

Enforce lean testing — meaningful coverage, no bloat.

Allowed:

• Unit tests: functions with non-trivial logic (transformations, state machines, validation)
• API tests: one happy path + one error path per new endpoint or action
• Manual/E2E: only for critical flows crossing ≥2 components not covered at a lower level

Not allowed:

• Tests for trivial getters, setters, pass-through functions
• Same assertion duplicated at unit + API + manual level
• "Test everything" catch-all entries without specific behavior described
• Coverage padding (tests added just to have them)

Per test entry check: "Would this test catch a real regression that no other test in the plan would catch?" If no → flag for removal or merge.