CLike Harper Extend Feature
Purpose
Harper Extend introduces the /extend command for controlled backlog evolution in an existing CLike/Harper project.
It appends new requirements to an already generated PLAN.md and plan.json without regenerating or mutating consolidated requirements.
The command is designed for projects that have already moved through IDEA β SPEC β PLAN β KIT β EVAL β GATE and need to add new REQs after a stable anchor, for example after REQ-006.
Plan-only append vs next release.
/extendappends REQs to the current plan. To evolve a delivered project to its next release β new needs merged into IDEA, SPEC and TECH_CONSTRAINTS, REQs typedADDED/MODIFIED/REMOVED, release foldersdocs/inputs/vN/anddocs/reference/vN/β use/idea --extend, the cascade mode of the same phase (seecommands.mdandarchitecture/ADOPT_AND_IDEA_EXTEND.mdΒ§12). This page describes/extend; the cascade shares its guard and adds its own rules.
Public Commands
/extend
/extend REQ-007 "ATDL v1 schema, validator and compiler"
/extend --after REQ-006
/extend --after REQ-006 --from attachment
/add-req
/add-req is an alias. The canonical phase and command remain extend.
Pipeline Position
IDEA β SPEC β PLAN β EXTEND β KIT β EVAL β GATE β FINALIZE
EXTEND is optional and repeatable.
It is not a replacement for /plan. It is an append-only evolution phase.
Core Guarantees
- Existing consolidated requirements are preserved by default.
- New requirements are appended after an anchor REQ.
PLAN.mdandplan.jsonremain aligned.SPEC.mdis updated only when the extension introduces new product/system capability scope.- Lane-guides are updated only when the extension introduces a new concern lane or materially extends an existing lane.
- All changes are auditable through an
EXTEND_*.mdreport. - Cloud and local-agent execution paths are both supported.
- Lane values are concern-oriented and must not be interpreted as implementation language.
Read Inputs
Required:
docs/harper/PLAN.md
docs/harper/plan.json
Optional, when present:
docs/harper/SPEC.md
docs/harper/IDEA.md
docs/harper/TECH_CONSTRAINTS.yaml
docs/harper/lane-guides/*.md
.clike/skills/**
.clike/packs/**
.clike/design-profiles/**
attachments
Written Outputs
Always:
docs/harper/PLAN.md
docs/harper/plan.json
docs/harper/EXTEND_<YYYY-MM-DD>_<FIRST_REQ>_<LAST_REQ>.md
Conditionally:
docs/harper/SPEC.md
docs/harper/lane-guides/<concern>.md
Forbidden by default:
src/
test/
tests/
runs/kit/
runs/eval/
Append-Only Policy
/extend must not rewrite existing REQs.
Default behavior:
REQ-001..REQ-N: read-only
REQ-N+1..REQ-M: appended
Existing REQ objects in plan.json must retain their semantic content.
Existing REQ sections in PLAN.md must not be rewritten. Shared sections such as dependency graph, milestone/backlog, and verification checkpoints may be extended only to include the new REQs.
SPEC.md Update Policy
SPEC.md is updated only when the new requirements add at least one of the following:
- new product capability
- new domain language
- new safety/compliance rule
- new integration boundary
- new user-facing behavior
- new non-functional constraint
The safest default is to append a section such as:
## Extension Scope β REQ-007..REQ-009
instead of rewriting consolidated SPEC content.
Lane-Guide Update Policy
Lane-guides are concern-oriented, not language-oriented.
Good lane examples:
workflow-dsl
operational-registry
risk-policy
Bad lane examples when used as implementation inference:
node
python
java
A lane-guide is created or updated only when the extension introduces a new capability concern or new evaluation guidance.
Cloud Execution Path
The cloud path is responsible for requirement interpretation and structured document generation.
The orchestrator sends the cloud model:
- current
PLAN.md - current
plan.json - optional
SPEC.md - optional lane-guides
- inline requirement text
- attachment text
- repository metadata and execution preference
The cloud response must produce file artifacts only under allowed Harper documentation paths.
Local-Agent Execution Path
The local-agent path is responsible for repository-local patching while preserving exact file structure.
The orchestrator emits an AGENT_EXTEND_CONTEXT.json package with:
- phase:
extend - anchor REQ
- new requirement input
- allowed write roots
- forbidden paths
- append-only policy
- validation expectations
The agent may write only:
docs/harper/IDEA.md
docs/harper/PLAN.md
docs/harper/plan.json
docs/harper/SPEC.md
docs/harper/lane-guides/
docs/harper/EXTEND_*.md
docs/harper/TECH_CONSTRAINTS.yaml (cascade only: /extend gets it restored)
Validation Rules
After /extend, CLike must validate:
PLAN.mdexists.plan.jsonexists and parses.- Anchor REQ exists when supplied.
- New REQ IDs are unique.
- New REQ IDs are contiguous unless explicitly supplied.
- Every new REQ has acceptance criteria.
- Every new dependency resolves to an existing or newly added REQ.
PLAN.mdandplan.jsonboth mention the new REQs.- Existing consolidated REQs are not modified.
- An
EXTEND_*.mdaudit report is written.
The extension enforces the plan rules deterministically before keeping the result
(extensions/vscode/extend-guard.js, cloud and local agent alike):
- existing REQs the agent changed or removed are restored as they were (fields CLike derives,
capabilitiesandcapability_exclusions, excepted), with a warning naming them; - duplicate ids, ids that are not
REQ-<number>or do not continue the sequence, a missing anchor, a requested REQ that was not added, a new REQ depending on an unknown REQ, or no new REQ at all reject the result: nothing is kept (a local agentβs PLAN.md and plan.json are put back); - a gap in the sequence and a stale
snapshot.totalare warnings; TECH_CONSTRAINTS.yamlis not an/extendoutput: a changed one is restored.
The cloud prompt carries the request of the command (anchor, requested REQ id, text, attachments)
in an EXTEND REQUEST section, so the cloud and the local agent receive the same instructions.
Audit Report
Example:
docs/harper/EXTEND_2026-05-19_REQ-007_REQ-009.md