feature-development

<!-- Generated by Paved plugin paved@2.29.0 from core.development.feature-development@0.8.0; edit Paved Core instead. -->

Feature development

When to use

In the planning and implementation phases of the feature workflow, and for any other change that adds or alters behavior. For restructuring without behavior change use refactoring; for throwaway exploration use prototyping.

Required context

None beyond the code. Useful when present: the feature map entry for the area, the architecture context (boundaries), the rules in scope and the verification profile, to know which checks exist before promising any.

Preconditions

• The requirement can be written as observable claims ("given X, the system does Y"). If it cannot, ask; do not fill gaps in a requirement with guesses.
• The affected code and the pattern to follow are known. If not, activate context-discovery first.

Procedure

1. Understand the requirement. Write it as claims, including the edge cases the requirement implies (empty input, missing data, limits, failure of a dependency). List what is out of scope.
2. Locate the affected code through the feature map or by following the entry point of the behavior. Name every file you expect to change. For technology-specific code, read the relevant knowledge under the selected adapter in the pinned Core runtime; use the project's adapter selection, and do not apply guidance from an unselected technology.
3. Plan the proof. Pick a profile check for each claim; plan artifacts and gaps now. Consider optional mutation checks for high-risk behavior or suite evaluation. They support only test-effectiveness claims about selected injected changes, never production behavior or non-regression.
4. Choose the working capacity. Use the lightest available model that can handle each bounded task reliably. Reserve stronger models for ambiguous requirements, architecture choices, difficult debugging, security-sensitive reasoning and final synthesis. Use cheaper, faster models for mechanical edits, narrow research, test drafting and independent checks when their output is easy to verify. Model names and capabilities vary by host; inspect its available choices instead of assuming a fixed catalog, and do not spend tokens asking a model to repeat context another session already has.
5. Delegate only independent work. Split work when tasks have clear inputs and outputs, can proceed without editing the same files or waiting on each other, and the expected time saved exceeds the cost of starting and coordinating sessions. Give each session a narrow brief with relevant context, expected result and constraints. Use separate sessions for parallel research, isolated test work or independent review; keep shared-state edits and tightly coupled reasoning in one session. Limit concurrent sessions to what the host and task can usefully support. When delegation will save time, register a machine-readable graph with paved delegation plan --run <id> --file <graph.yaml> --json, bound to the approved plan digest. Include task dependencies, exact read/write paths, output contracts and model policy. Keep concurrent write scopes disjoint. Use paved delegation ready --run <id> --json to see what can start. Show the complete graph to the user and obtain explicit approval before paved delegation approve --run <id> --approve --json; approval is tied to the immutable graph digest. Start work only after approval. Paved validates and records the graph; the active host owns native agent/session creation and work. Use Claude Code's native subagents when available. In Codex, use native collaboration tools when available and account for delegated agents inheriting the parent model and execution environment when the host offers no per-task routing. Inspect the host's actual model and reasoning controls; map economy, balanced and frontier to its lightest suitable options rather than assuming a fixed model catalog. Keep stronger capacity for ambiguity, architecture, difficult debugging and security-sensitive tasks. Treat requested reasoning effort as guidance if the host cannot honor it. Ask paved delegation capabilities --host <claude-code|codex> for host guidance. Claude Code subagents support per-invocation model and effort selection; prefer isolated worktrees for parallel edits. Codex routing and isolation depend on the active host configuration. Host permissions remain authoritative. Start with --isolation shared-workspace or --isolation isolated-worktree; shared-workspace writers are serialized. Record the actual host/model/effort with paved delegation start; after the host reports completion, save a concise result under .paved/generated/delegation-results/<run-id>/ and use paved delegation finish with the result path, outcome, each changed path via repeated --changed-path, and available usage. Paved checks reported paths against exact write scopes; paths from isolated worktrees remain host-reported and require primary-agent diff inspection. For an interrupted session, verify it has stopped before paved delegation recover --run <id> --task <id> --confirmed-stopped --note <reason>. Recovery preserves the attempt and makes it retryable. Usage is host-reported, not independently verified. Never store prompts, credentials or raw session ids. Keep short, tightly dependent or shared-file tasks in the primary session when startup and coordination cost exceeds the likely time saved.
6. Integrate centrally. The primary agent owns the approved plan, resolves conflicts, and checks delegated changes against the plan and repository. It remains responsible for tests, verification, evidence and completion. A delegated result is input, not proof: inspect its diff and rerun affected checks. Do not bypass approvals or change scope without updating the plan.
7. Choose the smallest complete solution. Check whether the behavior is needed as stated, then look for a project helper or pattern, platform feature, or installed dependency before adding code or dependencies. Avoid unrequested options, abstractions and future flexibility. Keep the diff readable; finish affected callers, tests and fixtures. Never reduce trust-boundary validation, data-loss handling, error handling, security, accessibility or explicit requirements. For a deliberate shortcut with a known limit, add shortcut: <limit>; revisit when <condition> in a source comment; paved gardener debt lists tracked markers without writing files. Remove the marker when resolved.
8. Test clear behavior before implementing it. For a behavior claim with a known result, write and run the lowest-level test first; confirm its intended failure before making the smallest passing change. If behavior is unresolved, prototype or ask first; refactors pin existing behavior with characterization tests.
9. Implement in small steps that mirror the chosen sibling: naming, structure, error handling, logging, configuration. The diff contains only what the claims need.
10. Complete the tests for every relevant level. Hand tests to the skill for each level: unit-testing for logic, integration-testing for boundaries with real collaborators, e2e-testing when the claim is a user-visible flow.
11. Run the fast checks after each meaningful step and fix failures before going on.
12. Clean up imports, parameters, files and flags the change left unused.
13. Self-review the diff with core.repository.diff and confirm with core.repository.status that no unintended file changed.
14. Verify and record every required check, then hand over to the verification phase.

For a Paved workflow, keep the durable plan at .paved/documents/plans/<run-id>.md. Put a behavior contract in .paved/documents/specs/<run-id>.md when the requirement needs one, and a task breakdown in .paved/documents/tasks/<run-id>.md when it helps execute the plan. Use the same workflow run id in related filenames and follow core.instructions.workflows for review.

Tools

core.repository.diff for self-review; core.repository.status for unintended files. Build and test commands come from the Tools named by Checks in the verification profile.

Rules

core.architecture.follow-existing-patterns and core.architecture.respect-declared-boundaries shape steps 2 and 4. core.security.no-secrets-in-source covers test data and examples as well as code. core.quality.evidence-before-completion governs step 9.

Verification

Required: unit. Recommended when the profile has them: build and static-analysis (they validate, but prove no behavior), integration for changed boundaries, e2e for changed user flows.

Evidence

A check result for every claim, the diff, and a gap for each claim without an available check.

Completion criteria

• Every claim has a passed check or a supporting artifact, or is an explained gap.
• The diff touches only files named in step 2, or the plan was updated to say why.
• No new static-analysis warnings in the changed files.

Failure modes

Failure	Signal	Response
Scope creep	Diff touches files unrelated to the claims	Revert the unrelated parts
New pattern by accident	Code differs in style from its siblings	Rewrite to match, or record why not
Proof chosen after the fact	Claims appear only after implementation	Re-plan the claims; confirm the tests assert them
Requirement grows during work	New claims appear mid-implementation	Stop and confirm them with a human

References

None.

Paved integration

Use the project-local Paved contract as the source of truth. Discover state with node "${CLAUDE_PLUGIN_ROOT}/scripts/paved.mjs" status --json, load only relevant .paved/project/ context, and invoke verification with node "${CLAUDE_PLUGIN_ROOT}/scripts/paved.mjs" verify --json. Always run it from the repository being worked on, never from the plugin directory. Do not edit generated integration files or bypass Paved lifecycle and ownership checks.