U Planning

SKILL: Planning

Purpose

This skill defines the standards, templates, and quality rules for the Planner Agent to produce consistent, traceable backlogs ready for development.

---

Canonical templates

Epic

## EPIC-XX: [Epic Name]

**Objective:** [One sentence: what business value this area delivers]
**Affected personas:** [E.g., BI Analyst, Administrator, End Customer]
**Success criterion:** [Observable metric or condition indicating the Epic is complete]
**External dependencies:** [Consumed external APIs, design system, third-party libraries]
**Priority:** High | Medium | Low
**Tasks:** [TC-XX, TC-YY, ...]

Task Contract

````yaml task_contract: id: TC- # Pattern: ^TC-[0-9]+$ # Example: TC-01

epic: EPIC- # Pattern: ^EPIC-[0-9]+$ # Example: EPIC-03

origin: # Enum: UC-NN | improve-NN | bug-NN | component-spec-gate | direct # Example: UC-04

type: # Enum: feature | bugfix | refactoring | spec | tech_debt

priority: # Enum: P0 | P1 | P2

scope: # Enum: frontend | backend # PROHIBITED: both

estimate: # Enum: S | M # PROHIBITED: L

dependencies:

• TC-

# Array of TC-XX ids. Use [] if no dependencies.

persona_coverage:

# Array of actors from spec.md §2 served by this task. # Example: [admin, end-user]

bdd_ref: # Reference to BDD Scenarios section in the feature spec. # Use null if no BDD reference applies.

executioncontract: exectype: # Enum: codegeneration | bugfix | refactoring | analysis | design | review | test_generation | validation | documentation

objective: # One intention only. No narrative.

input: references:

• path:

section: version: # Array of structured references consumed by the executing agent.

known_context:

# Array of facts already established — no inference required.

assumptions_allowed:

# Array of assumptions the agent is permitted to make. # Empty array = no assumptions allowed.

constraints:

# Array of hard constraints. One rule per item.

output: format: yaml schema:

• files_created
• files_modified
• acceptancecriteriacoverage
• edge_cases
• spec_divergences
• tech_debt
• tests
• inference_log

validation: criteria:

# Each criterion must be independently verifiable. # No subjective criteria permitted.

fallback: onmissinginput: blocked template: .claude/skills/u-shared-templates/blocked-report.yaml

````

> scope field: determines which domain orchestrator processes the task. For domain: backend projects, all tasks default to backend. For domain: frontend, all tasks default to frontend. For domain: fullstack, the Planner must explicitly set backend or frontend per task. Tasks with scope: both are prohibited — split into two linked task_contracts (see granularity rules).

---

Task Contract Granularity Rules

| Signal | Action | |---|---| | estimate: L attempted | Prohibited — split into multiple TCs with estimate S or M | | validation.criteria > 8 items | Likely 2 task_contracts | | task covers > 2 screens or distinct flows | Split by screen or flow | | scope: both attempted | Prohibited — split into TC backend + TC frontend with explicit dependency (frontend depends on backend) | | dependencies in a cycle | Design error — resolve before delivering the backlog | | backlog > 15 tasks | Deliver by Epic — do not process the entire file at once |

---

Persona coverage gate

Before finalizing the backlog, verify:

• List all actors defined in spec.md §2 (or CLAUDE.md)
• For each actor: confirm that at least one TC with persona_coverage includes that actor
• If any actor has no coverage: create a TC or register as open question

| Actor | Covered by | |---|---| | {PersonaName} | TC-XX, TC-YY |

---

Requirement coverage gate (Rec A)

Before finalizing the backlog, verify that every requirement defined in the referenced specs maps to at least one Task Contract — and cross-check against the original requirement text passed in the activation prompt (Original requirement:):

• Every UC-NN in a referenced *.spec.md is the origin of a TC, or is explicitly handled within another TC's scope.
• Every FEAT-NN in a referenced *.feature.spec.md is referenced by a TC's bdd_ref.
• A requirement intentionally left out of this wave is recorded explicitly in the backlog (e.g. an ## Out of scope note), never silently dropped.

| Requirement | Covered by | Out-of-scope (reason) | |---|---|---| | {UC-NN / FEAT-NN} | TC-XX | — |

> Enforced deterministically by check_spec_requirements_covered.py at dev exit: an uncovered UC/FEAT blocks the dev→review transition. Do not rely on this prose alone — but producing an orphan requirement here is a backlog defect.

---

Task contract — how to populate

Planner fills execution_contract YAML block for each Task Contract in Step 3B before saving backlog.md. This is the Orchestrator's primary context-mounting source — replaces ad hoc inference at Developer activation.

exec_type

| Task Type | exectype | |---|---| | feature | code_generation | | improve | code_generation | | bugfix | bug_fix | | refactoring | refactoring | | spec | documentation | | techdebt | refactoring |

objective

Single operational sentence describing what the agent must produce. Not a business narrative. Example: "Implement POST /auth/login endpoint with JWT emission and BR-01 credential validation."

input.references — spec-first mode

Each reference must include version — the spec version at Planner time. This pins the spec consumed for traceability from backlog → delivery → audit.

Backend:

references:
  - path: "{SPECS_DIR}/domains/{domain}/openapi.yaml"
    section: "paths: POST /resource, GET /resource/{id}"
    version: "1.0.0"
  - path: "{SPECS_DIR}/domains/{domain}/back/{domain}.back.md"
    section: "BRs: BR-01, BR-02; EVs: EV-01; tables: users"
    version: "1.0.0"
  - path: "{SPECS_DIR}/_global/error-codes.md"
    section: "codes: AUTH_001, RESOURCE_NOT_FOUND"
    version: "1.0.0"

Frontend:

references:
  - path: "{SPECS_DIR}/front/features/{feature}.feature.spec.md"
    section: "§1 endpoints, §4 transforms, §7 adapters, §9 BDD"
    version: "1.0.0"
  - path: "{SPECS_DIR}/domains/{domain}/openapi.yaml"
    section: "consumed: operationId1, operationId2"
    version: "1.0.0"
  - path: "{SPECS_DIR}/front/components/{Name}.component.spec.md"
    section: "§2 Props, §3 States, §4 Events"
    version: "1.0.0"
  - path: "{SPECS_DIR}/_global/error-codes.md"
    section: "codes: UI_ERR_001"
    version: "1.0.0"

> Version source: read from the version: field in each spec file's frontmatter or YAML header. If absent, use git short hash at planning time, or "unknown" as fallback — never omit the field.

> No {SPECS_DIR} (Improve mode without approved specs): set references: [{path: codebase, section: "Developer discovers via inspection"}]

input.known_context

Pre-loaded facts that do not require file reads. Reduces unnecessary discovery steps. Example: ["UserService extends BaseService in src/shared — do not duplicate", "JWT issued via injected JwtService"]

input.assumptions_allowed

Explicit list of inference types the Developer may use without declaring in inference_log. Example: ["reuse existing repository patterns", "follow established route naming conventions"] Inferences NOT listed here must be recorded in inference_log in the delivery.

constraints

Task-specific rules beyond CLAUDE.md. Primary use: cross-task contract preservation. Example: ["preserve GET /users response schema — also consumed by TC-03"] Empty list when no constraints apply.

output.schema

Fixed for most tasks — matches delivery-body YAML fields in the delivery template. Override only for exec_type: documentation (Spec tasks) which produce .spec.md artifacts.

validation.criteria

Technical criteria the Developer self-validates before setting qa_ready: true. Example: ["all tests pass locally", "no hardcoded values — only design tokens via var(--token)", "no endpoint fields outside openapi.yaml contract"]

fallback

Always: on_missing_input: blocked + template: .claude/skills/u-shared-templates/blocked-report.yaml Never leave empty — if all inputs available, still declare the fallback.

---

Numbering convention

EPIC-01, EPIC-02, ...
TC-01, TC-02, ...    (none)
TC-02 -> TC-01
TC-03 -> TC-01
TC-04 -> TC-02, TC-03

Use -> to indicate "depends on". If there is a cycle, it is a design error — resolve it before delivering the backlog.

---

Backlog quality checklist

Before saving backlog.md, validate:

• [ ] Every TC has persona_coverage with at least 1 persona
• [ ] Every TC has bdd_ref declared (FEAT-NN §9 or null)
• [ ] No TC has estimate L — prohibited without splitting into S or M
• [ ] All dependencies are explicit in the map
• [ ] There are no dependency cycles
• [ ] Open questions are marked with Warning
• [ ] Personas used in task_contracts are defined in CLAUDE.md or the project context
• [ ] Task Contract order in the backlog respects dependencies (tasks without dependencies first)
• [ ] Every TC has executioncontract populated: exectype defined, objective written, input.references declared (spec-first) or marked as codebase, validation.criteria non-empty for codegeneration/bugfix types

---

Personas — how to define

If the project does not have defined personas, the Planner must list them before creating Task Contracts:

## Project personas

- **[Name]:** [Who they are, what they do, their primary goal in the system]
- **[Name]:** [...]

Generic personas like "user" or "admin" are allowed only if the system truly does not distinguish profiles.

---

Customization via CLAUDE.md

The project's CLAUDE.md can (and should) override parts of this skill. When reading CLAUDE.md, extract:

| What to look for | Used in | |---|---| | Defined personas or user profiles | Task Contract personacoverage | | Business domain and specific terminology | validation.criteria language | | Technical constraints (e.g., component framework, design system, router routes) | constraints and knowncontext | | Existing components or pages | Dependencies and known_context |

If CLAUDE.md does not define personas, the Planner must create them in the backlog before writing any Task Contract.

---

Final backlog.md structure

# Backlog

_Created on: YYYY-MM-DD_
_Last updated: YYYY-MM-DD_
**Layer:** semi-permanent

---

## Personas
[persona list]

---

## Epics
[list of epics using the canonical template]

---

## Task Contract overview

| ID | Title | Persona | Priority | Epic | Status |
|----|-------|---------|----------|------|--------|
| TC-01 | [title] | [persona] | P0 | EPIC-01 | Backlog |
| TC-02 | [title] | [persona] | P1 | EPIC-01 | Backlog |

---

## Task Contracts by priority

### P0 — Must Have
> Without these Task Contracts the product does not work or lacks minimum value.

[P0 task contracts grouped by epic, in dependency order]

### P1 — Should Have
> Important for the experience, but do not block launch.

[P1 task contracts grouped by epic, in dependency order]

### P2 — Nice to Have
> Desirable when capacity allows — do not compromise the current cycle if deferred.

[P2 task contracts grouped by epic, in dependency order]

---

## Dependency map
[text graph]

---

## Journey maps by Epic

> Include for each Epic with 3 or more Task Contracts in mandatory sequence.
> Optional for Epics with parallel or independent Task Contracts.

```mermaid
journey
  title EPIC-XX: [Epic Name]
  section [Phase 1]
    TC-01 [short title]: 5: [Persona]
    TC-02 [short title]: 3: [Persona]
  section [Phase 2]
    TC-03 [short title]: 4: [Persona]

---

Open questions

[list of items marked with Warning that need answers before development]

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zig999](https://github.com/zig999)
- **Source:** [zig999/siegard-code](https://github.com/zig999/siegard-code)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.