perfectcode-zen-implement

PerfectCode Zen — Implement

A structured implementation workflow that executes a written plan from .opencode/plans/ using parallel engineering agents, followed by quality gates and testing. Nothing is declared done until all tests pass.

Orchestrator: build agent — this workflow is always started and driven by the build agent. The build agent reads the plan, decomposes work, delegates to coders, escalates to consultants when blocked, and closes the workflow.

Prerequisite: A plan file must exist in .opencode/plans/. Read it carefully and thoroughly before doing anything else. Every decision must trace back to the plan. Do not improvise, skip, or reinterpret scope.

Step 1 — Start as the Build Agent

This workflow is owned by the build agent from start to finish. The build agent does not write code — it orchestrates. Its responsibilities are:

Read and deeply understand the plan in .opencode/plans/
Decompose the plan into atomic implementation tasks
Delegate tasks to developer-prime and developer-fast
Escalate to consultants the moment anything is unclear, blocked, or risky
Verify quality gates and ensure all tests pass before closing

Do not skip this agent assignment. The build agent is the single point of accountability for the entire workflow.

Step 2 — Read the Plan Carefully and Thoroughly

Locate the plan file in .opencode/plans/. Read it in full before taking any action. Pay close attention to:

Goals and scope
Architecture and design decisions
Implementation tasks and their dependencies
Security, performance, and database considerations
Testing strategy and acceptance criteria

Follow every instruction in the plan thoroughly. The plan is the source of truth. If the plan says to do something a specific way, do it that way exactly. Do not improvise. If something in the plan is ambiguous, escalate to the appropriate consultant before proceeding (see Step 4).

Step 3 — Decompose and Track All Tasks

Break every implementation item in the plan into atomic, actionable tasks. Register all tasks in TodoWrite immediately. Rules:

Mark a task in_progress the moment work begins on it
Mark a task completed the moment it is verifiably done — do not batch
Only one task should be in_progress at a time
Never declare a task complete without evidence (tests pass, code reviewed)

Step 4 — Delegate to Coders

Assign implementation tasks to the appropriate coder agent and run independent tasks in parallel:

Task type	Assigned agent
Complex, multi-file, or long-context work	`developer-prime`
Scoped, single-file, boilerplate, or high-volume tasks	`developer-fast`

Run all independent tasks simultaneously. Never serialise work that can be parallelised.

Load Language Skills Before Delegating

Before dispatching each task, load the skill matching the target technology so the coder agent inherits the correct style conventions:

Technology	Skill
TypeScript / TSX	`typescript-style`
JavaScript / JSX	`javascript`
Python	`python`
Go	`go`
CSS	`css`
HTML	`html`
Tailwind	`tailwind-css`

Task Prompt Template

Give every coder agent a fully-formed prompt — never a vague description:

Task: <specific action from the plan>

Context: <relevant background and any consultation outputs>

Requirements:
  - <requirement 1>
  - <requirement 2>

Files to modify:
  - <path>

Files to create:
  - <path>

Architectural guidance: <from principal-architect or solution-architect if consulted>
Security requirements: <from security-expert if consulted>
Database guidance: <from database-architect if consulted>

Success criteria:
  - <how to verify this task is done>
  - <tests that must pass>

Per-Task Verification

After each coder agent completes a task, verify before marking it done:

Run the relevant tests (npm test / pytest / go test ./...)
Check type errors (tsc --noEmit / mypy / go vet)
Run linter / formatter
Confirm expected behaviour
Mark the todo completed immediately — do not batch

Never advance to the next task while the current one has a failing check.

Step 5 — Consult Immediately When Blocked or Uncertain

If anything goes wrong, gets stuck, requires a decision not covered by the plan, or carries architectural/security/data risk — stop and consult before continuing. Do not guess. Do not proceed on assumptions.

Escalate to the relevant consultant(s) immediately and in parallel if multiple perspectives are needed:

Situation	Consult
Architecture or system design question	`principal-architect`
Service design or cross-component decision	`solution-architect`
Data model, schema, or query concern	`database-architect`
Security, auth, or threat modelling concern	`security-expert`

Consultants operate in Think → Advise → Review mode: they analyse the situation, give a concrete recommendation, and review the outcome. Their guidance must be incorporated before work continues.

Consultation is not optional when blocked. It is a required part of the workflow.

Step 6 — Quality Gates

After all coding tasks complete, run the following reviews in parallel before declaring the implementation done:

security-expert — verify all security mitigations from the plan are correctly implemented
principal-architect — verify the implementation matches the agreed design
solution-architect — verify service boundaries and interfaces are correct
database-architect — verify schema, migrations, and queries are sound

Address every finding before moving to testing.

Step 7 — Testing and Validation

Run the project's full test suite. If tests are missing for new code, delegate to developer-fast to add them per the testing strategy defined in the plan. All tests must pass before the workflow closes. No exceptions.

Step 8 — Documentation and Git Review

Before presenting the final summary, do a clean-up pass:

Update code documentation — add JSDoc / docstrings to all new public APIs; add inline comments for non-obvious logic.
Update README if the feature requires new setup steps, environment variables, or changed behaviour.
Update .env.example for any new environment variables introduced.
Remove all debug artefacts — no console.log, no commented-out code, no temporary files.
Run git status and git diff --stat to confirm only intended files changed and no unintended modifications are included.

Step 9 — Final Summary

Present a concise summary covering:

What was built
Which agents contributed
Tasks completed (count)
Files changed (count, added vs modified)
Test results (passing / total, coverage if available)
Any deviations from the original plan and their justifications
Warnings or post-deployment considerations (migrations, env vars, etc.)
Suggested next steps (review git diff, commit, open PR, deploy)

Key Rules

Build agent owns the workflow. This workflow starts and ends with the build agent.
Read the plan carefully and thoroughly. Every action must trace to the plan.
Follow instructions thoroughly. Do exactly what the plan specifies. Do not reinterpret or skip steps.
Load language skills before delegating. Give coders the right style context.
Use the task prompt template. Never delegate with a vague description — include task, context, files, consultation outputs, and success criteria.
Verify each task before moving on. Run tests, type-check, and lint after every task. Do not accumulate failures.
Delegate to developer-prime and developer-fast. These are the two coder agents in this workflow.
Consult immediately when blocked. principal-architect, solution-architect, database-architect, and security-expert are on call for Think → Advise → Review.
Parallel by default. Never run independent tasks or consultations sequentially.
Track every task. Use TodoWrite throughout. No task is done until marked completed.
Quality gates are mandatory. Do not skip the parallel review step before testing.
All tests must pass. Do not close the workflow with failing tests.
Clean up before closing. Update docs, remove debug code, verify git status before the final summary.

Agent Roster

Orchestrator

Agent	Role
`build`	Workflow owner — reads plan, delegates, escalates, closes

Implementers (write code)

Agent	Specialty
`developer-prime`	Complex, multi-file, long-context, and frontend tasks
`developer-fast`	Scoped, single-file, boilerplate, and high-volume tasks

Consultants (Think → Advise → Review — read-only, no code changes)

Agent	Specialty
`principal-architect`	High-level system strategy, cross-service architecture, technical governance
`solution-architect`	Concrete service designs, cross-component interfaces
`database-architect`	Data modelling, schema, query optimisation, migrations
`security-expert`	Threat modelling, cryptography, auth, secure coding

Workflow at a Glance

Build agent starts
    │
    ▼
Read plan from .opencode/plans/<name>.md (carefully and thoroughly)
    │
    ▼
Decompose into atomic tasks (TodoWrite)
    │
    ▼
For each task:
    Load language skill → build task prompt → delegate
    ├── developer-prime  (complex / multi-file)
    └── developer-fast   (scoped / single-file)
    │
    ▼ (after each task)
Per-task verification: tests → type-check → lint → mark completed
    │
    ▼ (if blocked or uncertain at any point)
Consult immediately (in parallel as needed)
    ├── principal-architect  → Think, Advise, Review
    ├── solution-architect   → Think, Advise, Review
    ├── database-architect   → Think, Advise, Review
    └── security-expert      → Think, Advise, Review
    │
    ▼
Parallel quality gates
    ├── security-expert
    ├── principal-architect
    ├── solution-architect
    └── database-architect
    │
    ▼
Testing and validation (all tests must pass)
    │
    ▼
Documentation update + git status review
    │
    ▼
Final summary (tasks, files, tests, deviations, next steps)