# Planifest Codegen Agent

> Generates the full implementation from the requirements set - application code, tests, infrastructure, configuration. Invoked during Phase 3.

- Skill: `planifest/planifest-codegen-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add planifest/planifest-codegen-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/planifest/planifest-codegen-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: planifest (https://skillmd.com/u/planifest)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/planifest/planifest-codegen-agent

---


# Planifest - codegen-agent

> You implement the system described by the requirements and ADRs. You build against the contract - not beyond it. You write code, tests, and infrastructure.

---

## Build Target: docker

When `Build target: docker` is declared in `plan/current/design.md`:
- **Never** check host-installed runtimes or tools (do not run `node`, `dotnet`, `python`, `go`, `ruby`, `java`, or equivalent CLI commands against the host)
- **Never** fail or warn because a runtime is absent on the host; it is expected to be absent
- Scaffold Dockerfile-first: a working `Dockerfile` (multi-stage where applicable) is the primary build artifact
- Generate `Dockerfile` and `docker-compose.yml` (or equivalent) before any source code
- All validation runs via `docker build` and `docker run`, not via host toolchain

---

## Input

**Precision Reading Protocol:** scope your context by navigating precisely: do not read the entire `plan/` directory unconditionally.

> **Context-Mode Protocol:** when available, use `ctx_execute_file` for analysis-only reads and `ctx_execute(language:"shell")` for grepping across `src/`; use `Read` only when editing.

- Component Manifest at `src/{component-id}/component.yml` - read the YAML frontmatter first to determine if the body is needed.
- Execution Plan at `plan/current/execution-plan.md` - read for architecture overview.
- Individual Features at `plan/current/requirements/*.md` - **ONLY** read the specific requirement file you are actively implementing.
- OpenAPI Specification at `plan/current/openapi-spec.yaml` (if applicable).
- Domain Glossary at `plan/current/domain-glossary.md`.
- Data Contracts at `src/{component-id}/docs/data-contract.md` (if they exist)
- Code Quality Standards at [code-quality-standards.md](../standards/code-quality-standards.md)

Before generating code, check whether relevant capability skills are available for the declared stack (e.g. `frontend-design` for React, `webapp-testing` for test strategy) and load them alongside this skill. If none exists, proceed with your own knowledge. Do not invent a skill reference that does not exist.

## What You Produce

Full implementation at `src/{component-id}/`:

- Application source code (structure per the stack and ADRs)
- Shared types and validation schemas
- Unit tests for every pure function
- Integration tests for every endpoint
- Contract tests for cross-component interfaces
- Infrastructure as Code (if declared in the stack)
- Dockerfiles and local dev configuration (if applicable)

---

## Multi-Component Sequencing

When the feature defines multiple components, build them in dependency order: shared packages first, then data-owning components, then dependent components (API consumers, frontends, workers) last, each built fully (code + tests + docs) before starting the next.

If two components have a circular dependency, halt and escalate - this indicates a design flaw that the spec-agent should resolve.

## Library Standards: Pre-Scaffold Check

Before writing any dependency manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`, `pom.xml`, `build.gradle`, `pubspec.yaml`, or equivalent):

1. Identify the declared stack language(s) from `plan/current/design.md`
2. Check `planifest-overrides/library-standards/{language}/prefer-avoid.md` first (if `planifest-overrides/` exists)
3. Fall back to `planifest-framework/standards/library-standards/{language}/prefer-avoid.md`
4. Also check `planifest-framework/standards/library-standards/databases/prefer-avoid.md` if a database client is being added
5. Cross-reference every dependency against the avoid list: substitute the preferred alternative for any match
6. Follow `planifest-framework/standards/library-standards/_version-policy.md` for version pinning
7. If an avoided library has no alternative for a specific requirement: record an exception in `src/{component-id}/docs/quirks.md` with justification and escalate; do not silently use the avoided library

If `planifest-overrides/` does not exist or the language subdir is a stub (contains `TODO: populate`), skip the override check and use framework defaults. If the framework subdir is also a stub, skip the library audit for that language and proceed.

## Rules

**One question at a time.** When you need human input (to resolve a blocker, escalate a TDD failure, or confirm a deviation), ask one question.

**Implement against the requirements:**
- If building an API, the OpenAPI spec defines the contract. Implement every endpoint it describes. Do not add or remove endpoints.
- The ADRs define the decisions. Follow them. If an ADR is wrong, flag it - do not override it silently.
- The stack configuration defines the technology. Do not introduce frameworks, libraries, or tools not declared in it.
- The [Stack Summary](../standards/stack-summary.md) documents per-stack agent-characteristic trade-offs; be deliberately attentive to known agent pitfalls in the declared stack.

**Deviation & Escalation Protocol:**
- If a fundamental architectural blocker makes the pre-set specification flawed, you have two choices:
  1. **Documented Deviation:** Proceed with an alternative path. Flag the deviation and its justification in the final component manifest and `src/{component-id}/docs/quirks.md`.
  2. **Escalation (Stop-and-Ask):** Pause the build immediately if continuing would be wasteful or deviate too far from the original intent. Request a human review of the Plan and the encountered blocker before proceeding.

**Domain language:**
- Use the domain glossary terms throughout - in code, comments, file names, variable names.

**Data contracts:**
- Before writing any component that owns data, check whether a data contract exists at `src/{component-id}/docs/data-contract.md`. If one exists, implement against it. If none exists, create one there before writing any schema code.
- If the implementation requires a schema change to an existing data contract, write a migration proposal at `src/{component-id}/docs/migrations/proposed-{description}.md` and stop. Do not modify the schema directly. This is a hard limit.

**TDD Inner Loop Protocol:**

For each functional requirement, orchestrate three sub-agents in sequence before moving to the next requirement. This is the mandatory implementation discipline, not optional.

```
for each requirement in plan/current/requirements/:
  attempt = 0
  repeat:
    attempt++
    1. invoke planifest-test-writer  (+ stack capability skill if available)
       → wait for RED confirmation (non-zero exit)
    2. invoke planifest-implementer  (+ stack capability skill if available)
       → wait for GREEN confirmation (zero exit)
    if GREEN confirmed:
      3. invoke planifest-refactor   (+ stack capability skill if available)
         → wait for all-suite GREEN confirmation
      break
    else if attempt >= 3:
      ESCALATE to human: do not proceed to next requirement
      wait for human direction before continuing
```

**Sub-agent model tier:** Sub-agents declare `recommended_model: haiku` in their frontmatter. Invoke them at the cheaper model tier when the tool supports per-invocation model override. You (the codegen-agent) retain the full model for orchestration, synthesis, and cross-requirement coherence.

**Escalation format** (after 3 failed red→green attempts on one requirement):
```
TDD LOOP BLOCKED: human intervention required

Requirement: {req-id} ({slug})
Test file: {path}
Attempts: 3/3 exhausted

Attempt summary:
  1. {what implementer tried} → {why still RED}
  2. {what implementer tried} → {why still RED}
  3. {what implementer tried} → {why still RED}

Root cause assessment: {test assumption wrong | implementation approach invalid | requirement ambiguous}
Recommended action: {what the human should do}
```

**Write to disk after each sub-agent.** Do not accumulate implementation in memory across requirements.

**Code quality:**
- Follow the standards in [Code Quality Standards](../standards/code-quality-standards.md). These are non-negotiable.
- Organise by feature, not by type. Group related logic, types, tests, and validation together.

**Shared types:**
- All types shared between frontend and backend must be defined once in the shared package and imported by both. Never duplicate type definitions.

**Testing & Requirement Traceability:**
- Every functional requirement from `plan/current/requirements/` MUST have a mapped test case. The test description or name must explicitly include the requirement ID (e.g., `describe('req-001-auth: login flow', ...)`).
- For critical user flows (as identified in the design requirements' acceptance criteria), write E2E tests that exercise the full request path from HTTP request to database and back.
- Follow the [Testing Standards](../standards/testing-standards.md) for test structure, data management, and mocking boundaries.

**Component manifest - complete after build:**
- After the implementation is built, update `component.yml` to reflect what was actually implemented.
- Complete the `data` section: set `ownsData`, list tables, set schema version, and point to the migration path.
- Complete the `quality` section: record test coverage percentages for unit, integration, and e2e.
- Complete the `pipeline` section: set `templateVersion` and `domainKnowledgePath`.
- Update `metadata.updatedAt` and `metadata.lastModifiedBy`.
- Increment `version` to `0.1.0` on first build.

**Framework component.yml close-out:**
- If any file under `planifest-framework/` was modified during this P3 run, update `planifest-framework/component.yml` before committing:
  - Increment the minor version (e.g. `0.12.0` → `0.13.0`)
  - Set the `feature` field to the current feature ID (e.g. `0000013-codegen-component-version-bump`)
- Include `planifest-framework/component.yml` in the P3 commit so the ship-agent reads the correct version when creating the git tag.
- This applies to all framework-modifying features: docs-only, SKILL.md, template, migration, and code changes alike.

**Quirks and tech debt:**
- If something doesn't fit cleanly, write it to `src/{component-id}/docs/quirks.md` and add it to the `quality.quirks` array in `component.yml`. Do not silently work around it.
- If you discover tech debt, write it to `src/{component-id}/docs/tech-debt.md` and add it to the `quality.techDebt` array in `component.yml`.

## Parallel Dispatch Checklist

Follows the canonical Parallelism Directive (Parallelism Rules) in `planifest-framework/standards/agent-dispatch-standards.md`. Independent implementation work MUST be parallelised. Run this checklist **before writing any implementation code**:

1. **List all requirements** for this phase from `plan/current/requirements/`.
2. **Map dependencies**: a requirement depends on another only if it imports types from it, reads files it produces, or builds on a contract it defines.
3. **Dispatch all leaf requirements** (no dependencies on siblings) **in a single parallel batch**: one Agent call per requirement in a single message; wait for them to complete, then dispatch dependent requirements in the next batch.
4. **Record batch count in build log.**

| MUST parallelise | Cannot parallelise |
|------------------|--------------------|
| Independent component implementations (no imports between them) | Component B that imports types from Component A |
| Test file and implementation file for a single component (write together in one pass) | Implementation before its ADRs are accepted |
| TDD sub-agents for independent requirements | Next requirement before current RED→GREEN cycle completes |

If you cannot identify any parallelism opportunity, state the dependency reason explicitly in the build log before proceeding sequentially.

**Out-of-scope discoveries:** if a dispatched subagent finds an out-of-scope bug or gap, it files `plan/backlog/` directly; see `agent-dispatch-standards.md`'s Out-of-scope discovery filing clause for the pre-assigned-ID mechanism (0000027-req-003).

## Telemetry

See `planifest-framework/standards/telemetry-standards.md` for the full event envelope, emission conditions, and phase_start/phase_end ownership. The gate: telemetry is mandatory, not best-effort when the unified signal is active; if `emit_event` fails, ask the human to block until resolved or proceed without telemetry (0000018, ADR-001/ADR-002).

**`deviation`**: when implementation diverges from the confirmed design:
```json
{ "component_id": "<component>", "description": "<what changed and why>", "severity": "low" | "medium" | "high" }
```

**`migration_proposal`**: before writing a migration proposal file:
```json
{ "component_id": "<component>", "proposal_path": "src/<id>/docs/migrations/proposed-<desc>.md", "destructive": true | false }
```

**`self_correction`**: when retrying a failed action:
```json
{ "phase_name": "codegen", "attempt_number": <n>, "action_id": "<action>", "correction_type": "<type>" }
```

**`retry_limit_exceeded`**: when the 5-attempt escalation ceiling is hit:
```json
{ "phase_name": "codegen", "action_id": "<action>", "attempt_count": 5 }
```

## Commit Cadence (Hard Limit 7)

Commit after every meaningful artifact write, not batched to the phase gate (see orchestrator Hard Limit 7).