intent-planner 0.13.1

package/templates/en/intent/drift-patterns.md

@@ -0,0 +1,68 @@
+# Drift Patterns (catalog of drift types)
+
+> Read by `/intent-discover` as the basis for terrain diagnosis (when `drift-watch: on`). This is a file you grow by adding, as types, the drifts you actually hit in your own project.
+
+## How to read this catalog
+
+- **This is not exhaustive.** The types listed here are only a starting point (1 seed + 2 generic). The premise is that you append the drifts you actually hit in your own project as types and grow this file over time.
+- Each type is matched against `drift-log.md` by its aggregation key (`id`). The more types you add, the wider the range over which you can name "easy-to-drift terrain" before you start work.
+- The two bundled generic types (`premature-abstraction` / `layer-leak`) are placed as **weak cues with different symptoms**. They are deliberately varied so your thinking does not fixate on a single strong representative example (`microservice-over-split`).
+- "Matching" a type is not a confirmation of drift. Terrain diagnosis assumes false positives. When a type matches, you **write the anti-direction / invariant first** to act before you drift all the way out.
+
+## How to write a type
+
+Append a new type with the schema below. Make `id` a unique kebab-case aggregation key (the `pattern` field in `drift-log.md` references this `id`).
+
+```markdown
+## id: <kebab-case aggregation key>
+- name: <short name>
+- symptom: <cue about the subject / how it is progressing; a weak cue discover matches against the subject>
+- Things to write first:
+  - Anti-direction: <anti-direction candidate to write before compass-ification when this type is suspected>
+  - Invariant: <the corresponding invariant candidate; if subject-dependent, discover concretizes it from context>
+```
+
+- Write `symptom` as a cue for matching, not as a strong decision condition meaning "if this matches it is definitely drift" (keeping it a weak cue avoids fixation).
+- "Things to write first" is the wording to make discover write into the Intent Tree's Open Questions / anti-direction candidates, before compass-ification, when this type is suspected. Discover concretizes the subject-dependent parts from context.
+
+---
+
+## id: microservice-over-split
+
+- name: Microservice over-splitting
+- symptom: Over-adapting to the virtue of "split it up and keep it loosely coupled" against a single intent, carving out more services / modules / packages than necessary. Cross-boundary calls and coordination cost grow, and the result becomes more complex and more loosely coupled than the original intent.
+- Things to write first:
+  - Anti-direction: Do not make "loose coupling / splitting" an end in itself. Only add a service / module when you can name one concrete problem that split solves.
+  - Invariant: Do not add boundaries (service / process / package splits) that the original intent does not require. Allow a split only when it matches an intent boundary (L3).
+
+## id: premature-abstraction
+
+- name: Premature abstraction
+- symptom: Starting to build shared code / generic base classes / config-driven frameworks while there are still only 1–2 use cases. Introducing layers or extension points for requirements that do not actually exist, justified by "we might use it this way in the future".
+- Things to write first:
+  - Anti-direction: Do not build abstraction / generalization ahead of time for future requirements that do not actually exist (wait for the rule of three).
+  - Invariant: Introduce an abstraction (shared base, generic framework, config-driven design) only when there are 3 or more real use cases, or when the intent explicitly requires generality.
+
+## id: layer-leak
+
+- name: Layer leak
+- symptom: A concern that should stay in a lower layer (domain logic, persistence, external I/O) leaks out into an upper layer (UI, handler, presentation), or dependency flows backward in the opposite direction. Each change is locally convenient, but the responsibility boundaries between layers gradually erode.
+- Things to write first:
+  - Anti-direction: Do not push domain logic or I/O into the presentation layer / handlers for short-term convenience. Do not take cross-layer shortcuts.
+  - Invariant: Preserve each layer's responsibility boundary (the direction of dependency). Upper layers may depend on lower layers, but lower layers do not depend on upper layers.
+
+## id: coinage-proliferation
+
+- name: Coinage-prone terrain
+- symptom: The AI keeps coining new terms that are absent from the canonical vocabulary (ubiquitous language) instead of reusing terms that already exist. Several phrasings pile up for the same concept, the vocabulary fragments, and the alignment of intent (the core of the product) erodes.
+- Things to write first:
+  - Anti-direction: Do not invent a new term for a concept that already has a canonical term. If you must introduce a new term, attach a one-line explanation at first occurrence.
+  - Invariant: Every term used traces to the glossary's canonical vocabulary, or is explained in one line at first occurrence. Do not add terms absent from the glossary without an explanation.
+
+## id: scope-creep
+
+- name: Scope-creep-prone terrain
+- symptom: An implementation instruction arrives later that exceeds an already-exported work unit's (packet's) declared scope (e.g., a front-end-only packet being asked to add back-end, authorization, or transaction-boundary work). Each addition feels locally natural, yet the packet-specific invariants that newly become necessary in the new territory (authorization, data consistency, transaction boundaries, idempotency) keep being left out as work piles up.
+- Things to write first:
+  - Anti-direction: Do not push instructions that exceed an exported packet's `## Scope` straight through cc-sdd. Return the new territory to intent as a separate packet.
+  - Invariant: The implementation stays within the target packet's declared scope (`## Scope` / `## Non-scope`). If it reaches new territory, establish that territory's packet-specific invariants (authorization, consistency, transaction boundaries, idempotency) first.

package/templates/en/intent/export-log/README.md

@@ -0,0 +1,12 @@
+# export-log/ (split-form active surface)
+
+export-log is a **packet-derived** record, so write it split into **per-packet files** `export-log/<packet-slug>.md`. Different packets touch different files, so tail-append conflicts are eliminated by construction (this also resolves the shared collision where cc-sdd / openspec exports append to the same single file).
+
+- Keep only the currently-referenced export records here (the active surface), kept thin.
+- Move terminal (no-longer-referenced) entries into `export-log/archive/<year>/`.
+- The `<packet-slug>` in the filename follows the existing packet slug rule (`intent-packets/rules/packet-format.md`). Do not use sequential numbering (a central counter like `0001`).
+- **The old `../export-log.md` is kept as a generated active mirror**: until reader cross-following is complete, the writer regenerates `../export-log.md` on every export by concatenating the split files in `exported_at` order (derived, never hand-edited). This keeps existing single-file readers from breaking.
+
+> This README is a **restatement** of the rule. The single source of truth is CONTRACT.md "Split & archive discipline for append-only records". Consult CONTRACT for placement decisions.
+
+Do not put real entries in the active surface; entries are generated in split form by the export writers (intent-export-cc-sdd / intent-export-openspec).

package/templates/en/intent/export-log.md

@@ -0,0 +1,6 @@
+# Export Log
+
+> `/intent-export-cc-sdd` appends one row per export (1 export = 1 row). The only writer is `/intent-export-cc-sdd`; the readers are the intent-check script, `/intent-status`, and `/intent-writeback`. It is used to cross-check for missed write-backs, so no manual editing is needed.
+
+| packet | exported_at | commit |
+|---|---|---|

package/templates/en/intent/glossary.md

@@ -0,0 +1,23 @@
+# Glossary (lightweight canonical vocabulary ledger, β)
+
+> A lightweight canonical ledger that gathers in one place the mother-set of the agreed-upon canonical vocabulary (ubiquitous language) for this project. `/intent-validate` reads it as the mother-set when it names, read-only, "a term not in the ledger = a suspected coinage". **Humans edit it; skills only read it and never modify it automatically.**
+
+## How to use this ledger
+
+- **Its purpose is limited to "gathering canonical terms plus spelling variants / synonyms".** It is not a dictionary for bulk-replacing terms with translations (no translation replacement that harms readability / discoverability).
+- **This is not exhaustive.** The premise is that you grow this file by appending rows as canonical terms increase. When you officially adopt a new term, register its canonical form, spelling variants, and a one-line explanation here.
+- **It is canonical (humans edit it).** The coinage-management skill reads this ledger only and never rewrites it automatically. Applying a rewrite suggestion is a separate action taken only after a human approves it.
+- When a term not in the "Canonical term" column appears in an intent artifact, detection offers it as a "suspected coinage" candidate. Proper nouns, established English terms, and legitimate new terms already given a first-mention one-line explanation are excluded.
+
+## Entry schema (minimal 3 fields)
+
+| Canonical term | Aliases & synonyms | One-line explanation |
+|---|---|---|
+| ubiquitous language | canonical vocabulary | The mother-set of correct terms agreed upon for the project. When the vocabulary fractures, alignment of intent breaks down. |
+| canonical vocabulary | ubiquitous language | The correct terms themselves registered in the ledger. A suspected coinage is judged as a term absent from this set. |
+| coinage-suspect | suspected coinage | The ID of the detection check that names, read-only, any term absent from the canonical vocabulary as a suspected coinage. |
+| glossary | vocabulary ledger | The lightweight canonical ledger (this file) that gathers canonical terms plus spelling variants / synonyms. The home of the mother-set. |
+| drift | — | A way of progressing that gradually departs from the original intent. drift-patterns catalogs it as terrain types. |
+| packet | — | The minimal unit of intent handed from intent to spec / implementation. Its provenance is stamped in frontmatter. |
+| compass | intent-compass | The compass that folds intent into Decision Rules and Invariants. |
+| intent tree | intent-tree | The canonical body of intent that holds objective / problem / direction in a hierarchy. |

package/templates/en/intent/intent-compass.md

@@ -0,0 +1,55 @@
+# Intent Compass
+
+> Updated by `/intent-compass`. Manages the decision criteria for preventing local optimizations.
+
+## North Star
+
+The final state this change wants to approach.
+
+## Current Drift
+
+How and from which intent the current state is drifting (this gap is called drift).
+
+## Direction
+
+The direction to strengthen in this work.
+
+## Anti-direction
+
+The direction to avoid this time. Also explicitly enumerate here each local optimization (favoring immediate fixes over the overall intent) and quick-fix refactor Claude tends to make. Examples: "fix some other processing while at it", "bulk replacement without tests", "push domain logic into the UI".
+
+## Invariants
+
+Behavior / API / data / UX / operational constraints that must never be broken.
+
+> Record here only the **universal** constraints confirmed as truly worth upholding via negative-form questions (e.g. "what is the worst that happens if we ignore this?") — do not mix in over-assumptions. Hold candidate packet-specific constraints in Open Questions.
+
+Only **project-universal invariants** are kept here:
+
+- **Project-universal invariants**: a small set of constraints to uphold across all work regardless of feature. Placing them in `.kiro/steering/` via `/kiro-steering-custom` makes them effective across all work (keep them small to minimize the increase in startup context).
+- The canonical home of **packet-specific invariants** (constraints upheld only within a specific work unit) is the Safety / Invariants section of each packet file (`.intent/packets/active/<packet_id>.md`). Do not write them in the compass. At export time they are baked into cc-sdd's tasks from the packet file. When a packet moves to the archive, its packet-specific invariants retire together with the packet file (no residue is left on the compass side).
+
+## Decision Rules
+
+The criteria when in doubt. Keep each as a lightweight ADR, one decision per entry: **Context** (the question and situation) / **Decision** (the option taken) / **Why** (the criteria) / **Alternatives considered** (a summary of the QOC Options not taken and why they were rejected) / **Consequences** (connection to Invariants and Anti-direction) / **Revisit when** (the condition for revisiting; when it cannot be determined, explicitly record "undetermined" instead of leaving it blank). When overturning a decision, add a new entry, mark the old entry as superseded with a reference to its successor, and move it with all 6 fields intact to `.intent/compass-archive.md` (only the active criteria remain in the compass).
+
+Examples:
+- **Context**: where the aggregation logic lives (inside the UI vs the domain layer) / **Decision**: place it in the domain layer / **Why**: matches the L3 boundary intent (the UI only renders) / **Alternatives considered**: inside the UI — rejected because mixing rendering and aggregation violates the L3 boundary intent / **Consequences**: impose the Invariant "do not push domain logic into the UI framework" on all packets / **Revisit when**: when display-only aggregation starts bloating the domain layer
+- **Context**: how to carry out a large replacement (bulk replace vs staged migration) / **Decision**: prefer rollbackable slices / **Why**: keeps behavior-preserving observable / **Alternatives considered**: bulk replace — rejected because a failure cannot be rolled back and behavior-preserving cannot be observed / **Consequences**: add "large-scale replacement without tests" to the forbidden Anti-direction / **Revisit when**: undetermined
+
+## Evidence
+
+The evidence supporting this intent. README, code, tests, logs, user problems, operational problems, etc.
+
+Updated (Invariants): —
+Updated (Decision Rules): —
+
+> The time each of the Invariants / Decision Rules sections was last updated. `/intent-compass` stamps it in ISO 8601 when it updates that section (the initial `—` denotes not-yet-stamped). It is the compass-side reference that read-only validation (intent-validate's stale check) compares against a packet's `updated_at`; a section left as `—` is excluded from comparison (skipped as unverified).
+
+## Open Questions
+
+Questions needed for decisions but still undetermined.
+
+> Among the constraints raised by negative-form questions, hold here the **packet-specific constraints (candidates)** that are upheld only within a specific work unit, until the destination packet is decided (they are transcribed into that packet's Safety / Invariants when the packet is opened).
+
+> You can answer at any time (planning can proceed even while questions remain unanswered). Edit this file directly, or tell the agent in conversation and it will be reflected on the next skill run. Add the `[by export]` tag only to questions that must be answered by export (questions without the tag can be answered at any time).

package/templates/en/intent/intent-tree.md

@@ -0,0 +1,59 @@
+# Intent Tree
+
+> Updated by `/intent-discover`. Do not mix canonical (confirmed) and inferred (guessed = Assumptions). L0–L4 are the levels of the intent hierarchy (Level; L0 = purpose … L4 = candidate work units).
+
+## L0: Product Purpose
+
+What does this product / app / subsystem exist for.
+
+> Record here, as canonical, the purpose confirmed with the user after acknowledging the inferred purpose (the settled purpose). Put unconfirmed / guessed ones in Assumptions.
+
+## L1: Desired Outcomes
+
+What state change do you want to cause for users, business, operations, developer experience. When designer-questions is on, add a `Measurement criteria:` line (how achievement is observed and judged) to each L1 item.
+
+> Record here the confirmed intended users (Actors) and the definition of success (whose state change, and what change). Put anything not yet confirmed in Assumptions / Open Questions.
+
+## L2: Capabilities
+
+The capabilities that support the Desired Outcomes. Write them as responsibilities/capabilities, not feature names.
+
+## L3: Behavioral / Architectural Intents
+
+The behavior / design intent that makes the Capabilities hold. Include boundaries, dependency direction, side effects, data consistency, UI/UX constraints, etc.
+
+## L4: Candidate Packets
+
+Candidate work units before dropping into implementation. A granularity slightly above an Issue and slightly before a spec.
+
+## PoC Experiment Definition (fill in when purpose: poc)
+
+> Updated by `/intent-discover` when purpose=poc. If purpose is not poc, this section may stay empty.
+
+### Hypothesis
+
+What this PoC is meant to verify.
+
+### Falsification Criteria
+
+What, if it cannot be observed, rejects the hypothesis.
+
+### GO-NO-GO Criteria
+
+The conditions for deciding whether to proceed or stop after the PoC completes.
+
+## Screen Rough Reference (fill in when designer-questions: on)
+
+> Updated by `/intent-discover` when designer-questions=on. If the target includes user-facing screens, record the path or link to the rough (wireframe, sketch, etc.); if you decided there is none, write the reason. If no UI applies, record "Not applicable".
+
+## Open Questions
+
+Undetermined items the human should review.
+
+> Hold here any purpose, definition of success, or intended user that could not be confirmed, until it is settled (move it to L0 / L1 once settled).
+
+> You can answer at any time (planning can proceed even while questions remain unanswered). Edit this file directly, or tell the agent in conversation and it will be reflected on the next skill run. Add the `[by export]` tag only to questions that must be answered by export (questions without the tag can be answered at any time).
+
+## Assumptions
+
+Premises the AI inferred. Do not mix guesses with canonical intent.

package/templates/en/intent/milestones/README.md

@@ -0,0 +1,10 @@
+# milestones/ (split-form active surface)
+
+milestones is an **event-derived** record, so write it split into **per-date+slug files** `milestones/<date>-<event-slug>.md`. Different events touch different files, so tail-append conflicts are eliminated by construction.
+
+- Keep only the currently-referenced milestone events here (the active surface), kept thin.
+- Move terminal (no-longer-referenced) entries into `milestones/archive/<year>/`.
+- The `<event-slug>` is derived from the event's natural-language text via the existing slug rule (`intent-packets/rules/packet-format.md`); `<date>` is recorded_at. Do not use sequential numbering (a central counter like `0001`).
+- **Manual entry**: milestones is a record the user fills in declaratively. In split form, create one file `milestones/<date>-<event-slug>.md` per milestone event and write a single `| event | recorded_at | note |` row (keep the event natural-language text verbatim — improve's Revisit matching and status's unconsumed-milestone detection read it).
+
+> This README is a **restatement** of the rule. The single source of truth is CONTRACT.md "Split & archive discipline for append-only records". Consult CONTRACT for placement decisions.

package/templates/en/intent/milestones.md

@@ -0,0 +1,22 @@
+# Milestones
+
+> Record project milestone events ("production setup finalized", "exposed as a public API", etc.) by appending one row each. The only writer is the user; the readers are `/intent-improve` (matching each event against the Decision Rules' `Revisit when`) and `/intent-status` (showing unaddressed milestones as remaining work). It holds no decisions, learnings, or state — it is solely for recording milestone events.
+
+## How this file operates
+
+- **append-only**: rows are appended only. Never rewrite or delete a past row (to avoid creating an asymmetry in the world-line anchor).
+- **the user fills it in declaratively**: milestone events are entered by hand by the user. This file does no automatic detection (the user is the one who records).
+- **write in split form (CONTRACT "Split and archive convention for append-only records")**: milestones is event-origin, so instead of appending to the end of this single file, create one **per-date+slug split file** `milestones/<date>-<event-slug>.md` per milestone event and write a single `| event | recorded_at | note |` row. `<date>` is recorded_at; `<event-slug>` is derived from the event's natural-language text via the existing slug rule (`intent-packets/rules/packet-format.md`) — do not use sequential numbering. Keep the event natural-language text verbatim (it is what readers match against). See `milestones/README.md` for placement details and CONTRACT for the source of truth. Terminal milestones may be moved into `milestones/archive/<year>/`.
+- **how readers use it**: `/intent-improve` matches each `event` against the `Revisit when` field of every Decision Rule via substring containment and raises matched Rules into the revisit re-proposal list. `/intent-status` notes any milestone that has been recorded but whose corresponding revisit is still unaddressed as remaining work. Both are read-only matches and never rewrite the compass automatically.
+
+## How to fill it in
+
+- **event**: a natural-language string matched against a Decision Rule's `Revisit when` via substring containment. Too short a string over-matches, so write a sufficiently specific natural-language phrase that makes clear which milestone was finalized (e.g., "production setup finalized on AWS ECS").
+- **recorded_at**: written in ISO 8601 (e.g., `2026-06-18`).
+- **note**: an optional remark (use `-` if not needed).
+
+| event | recorded_at | note |
+|---|---|---|
+<!-- Example row (this comment line is not included in the real table):
+| production setup finalized on AWS ECS | 2026-06-18 | infra direction finalized at the dev offsite |
+-->

package/templates/en/intent/mode.local.md

@@ -0,0 +1,23 @@
+# Active Mode (Local)
+
+> Updated by `/intent-discover` when it confirms the mode. This is the working state (how the intent is being worked through) shared across intent-* skills.
+> **This file is local-only (git-ignored).** To prevent each contributor's working mode from colliding across a team or parallel sessions, `mode` / `designer-questions` / `purpose` (how the work is framed) live here. Policies you want to share (Enforcement / Drift-watch) live in `mode.md` (tracked).
+
+- **mode**: (undetermined — running `/intent-discover` recommends and confirms it)
+- **selected**: (confirmation date, ISO 8601)
+- **reason**: (why this mode was chosen)
+- **definition**: (e.g. `.intent/modes/standard.md`)
+- **designer-questions**: (undetermined — on / off. Proxy for the designer's questions. `/intent-discover` explains, confirms, and records it.)
+- **purpose**: (undetermined — poc / product. When designer-questions is on, `/intent-discover` confirms and records it.)
+- **format**: (undetermined — cc-sdd / openspec / to-spec. The output shape of the work = which exit to take. Optional. `/intent-discover` recommends, confirms, and records it. When unspecified, the exit is inferred from the case type.)
+
+## How this file is handled (shared convention across skills)
+
+- `/intent-discover` recommends the mode → user confirms → the result is written here.
+- `/intent-compass` / `/intent-packets` / `/intent-export-cc-sdd` etc. read this file and act per the mode definition in `definition`.
+- **Backward-compatible read (read fallback)**: readers resolve mode state in the order **this file (`mode.local.md`) → otherwise the old `mode.md` mode state → otherwise the `standard` default**. Legacy scaffolds (where mode state only exists in `mode.md`) are not broken.
+- **When this file is undetermined / absent**: each skill continues with `standard` as the default mode (does not stop) and notes in its Open Questions that "the mode is undetermined; running `/intent-discover` to confirm it is recommended."
+- This is distinct from the stop-and-guide behavior when prior artifacts (tree/compass/packets) are missing. Absence of mode state alone does not stop.
+- **When designer-questions / purpose are unrecorded or the lines are absent (legacy scaffold)**: each skill continues treating them as undetermined and notes it in its Open Questions. Readers always evaluate designer-questions first (the purpose value is not referenced unless designer-questions is recorded as on). Only `/intent-discover` writes designer-questions / purpose.
+- **The format read contract (three unspecified forms)**: `format` is an optional field recording the output shape of the work (which exit to take = cc-sdd / openspec / to-spec). Readers (the exit decision in `/intent-packets`, the preflight in the export skills) treat the following three forms identically as **unspecified**, and fall back — without stopping — to **inference** from the case type (mode, presence of `.kiro/`, etc.): (1) the `format` line is absent (legacy scaffold / existing environment); (2) a placeholder value (`(undetermined — …)`); (3) a value outside the range (cc-sdd / openspec / to-spec). Only when `format` is explicitly set to a valid value do readers resolve that exit deterministically. Only `/intent-discover` writes `format`, and each skill keeps working as before when it is unspecified (backward compatible).
+- **Why local-only**: `mode` / `designer-questions` / `purpose` are dynamic state tied to "who is working on what right now." Sharing them via git causes collisions — another member's working mode arriving via pull, or being overwritten by a parallel session. Hence they are git-ignored (the installer registers them in `.gitignore`). Policies you want to share (Enforcement / Drift-watch) live in the tracked `mode.md`.

package/templates/en/intent/mode.md

@@ -0,0 +1,32 @@
+# Shared Policy
+
+> This file holds **team-shared (git-tracked)** policies: `Enforcement` (writeback enforcement) and `Drift-watch` (drift monitoring).
+> **How the work is framed (`mode` / `designer-questions` / `purpose`) lives in `mode.local.md` (local-only, git-ignored).** They are separated to avoid collisions across a team or parallel sessions.
+> **Backward compatibility**: legacy scaffolds kept mode state in this file too. Readers read `mode.local.md` first and fall back to this file's mode-state lines (if present).
+
+## Enforcement (user-managed)
+
+> Only the user edits this section. Skills, including `/intent-discover`, never modify it (read-only).
+
+- **enforcement**: off
+- **enforcement-threshold**: 5
+- **enforcement-exclude**: 
+
+- **enforcement** — strength of writeback enforcement. One of `off` | `remind` | `gate`:
+  - `off` (default): no checks. Same behavior as before.
+  - `remind`: warns only when a writeback gap is detected. Does not stop.
+  - `gate`: stops export / push when a writeback gap is detected (explicit continue or `--no-verify` escape hatches remain).
+- **enforcement-threshold** — the commit count at which a writeback gap is judged stale. A positive integer (default: 5).
+- **enforcement-exclude** — path prefixes excluded from the staleness count (comma-separated relative path prefixes; may be left empty). `.intent/` is always implicitly excluded.
+- Toggle by editing this file directly. Unspecified / invalid values are treated as off / 5 / no exclusions and do not stop.
+
+## Drift-watch (user-managed)
+
+> Only the user edits this section. Skills, including `/intent-discover`, never modify it (read-only).
+
+- **drift-watch**: off
+
+- **drift-watch** — strength of drift monitoring. One of `off` | `on`:
+  - `off` (default): does nothing. Same behavior as before.
+  - `on`: terrain diagnosis at discover, compass-conformance warnings at the export boundary, and logs detections to drift-log.md. **All warning-only; never stops** (distinct from enforcement's gate; assumed to have false positives, so it does not stop).
+- Toggle by editing this file directly. Only the two values off|on; there is no stopping (gate-equivalent) value. Unspecified / invalid values are treated as off and do not stop.

package/templates/en/intent/modes/README.md

@@ -0,0 +1,28 @@
+# Modes — the extension point for Intent-working algorithms
+
+This directory holds "modes". A mode is a strategy that defines how to work out the Intent (a combination of algorithms). `/intent-discover` recommends a mode based on the repository situation, and the confirmed mode is recorded in `../mode.md`. Subsequent commands read `mode.md` and operate according to the corresponding mode definition.
+
+## 3-layer structure
+
+How to work out the Intent is separated into three layers.
+
+1. **Mode** (`modes/*.md`) — the phase → algorithm combination table (this directory)
+2. **Algorithm** (each skill's `rules/algo-*.md` / `rules/map-*.md`) — individual Intent extraction/conversion techniques
+3. **Skill** (`.claude/skills/intent-*/SKILL.md`) — the entity that loads a mode and executes
+
+## Bundled modes
+
+- `standard.md` — GORE-lite + QOC + Example Mapping + map-cc-sdd. The standard (default) general-purpose mode. Used for new products, and also for existing projects when no situation-specific mode applies.
+- `refactor.md` — GORE-lite + Drift Analysis + Migration Slicing + QOC + map-cc-sdd. For refactoring/redesigning large existing projects.
+- `behavior-unknown.md` — GORE-lite + Example Mapping + Characterization Test + QOC + map-cc-sdd. For legacy with unknown behavior.
+- `feature-growth.md` — GORE-lite + Impact Analysis + QOC + Example Mapping + Additive Slicing + map-cc-sdd. For adding new features to an existing, running system.
+- `non-code.md` — GORE-lite + QOC + Example Mapping + map-cc-sdd. For non-program deliverables (documents, business processes, research/decision-making) (produce readable deliverables without using cc-sdd/openspec).
+
+## Adding a new mode
+
+1. Add one `modes/<your-mode>.md` to this directory. Using `standard.md` as a template, write the combination table of which algorithm each phase (discover/compass/packets/export) uses, and the applicable situations.
+2. If the existing algorithms (GORE-lite/QOC/Example Mapping/map-cc-sdd) suffice, you may simply reference them.
+3. Only when a new algorithm is needed, add `algo-<name>.md` to the corresponding skill's `rules/` and reference it from the mode definition.
+4. Add the conditions for recommending the new mode to `/intent-discover`'s mode-recommendation logic (`intent-discover/rules/mode-selection.md`).
+
+`refactor.md` / `behavior-unknown.md` / `feature-growth.md` are already bundled. Use the procedure above when you want to add yet another mode.

package/templates/en/intent/modes/behavior-unknown.md

@@ -0,0 +1,57 @@
+# Mode: behavior-unknown
+
+The mode for legacy code whose behavior is unknown: pin down the observable behavior with examples, lock the unknown behavior with characterization, and then derive intent.
+
+## The algorithms this mode combines
+
+| Phase | Algorithm | Purpose |
+|---|---|---|
+| Intent Tree construction | **GORE-lite** (lightweight Goal-Oriented Requirements Engineering) | Progressively decompose the goal into L0(purpose)→L1(outcomes)→L2(capabilities)→L3(behavior/architectural intent)→L4(candidate packets). When the spec has been lost, place L3 as inferred (guessed) rather than confirmed, and corroborate it later with characterization |
+| Recording decisions | **QOC** (Questions-Options-Criteria) | Preserve design decisions as "question, options, selection criteria" and flow them into the Compass's Decision Rules / Open Questions |
+| Concretizing behavior / packet decomposition | **Characterization Test** → **Example Mapping** | For unknown behavior, first lock "this is how it works now" as observation points with Characterization Test, then organize those observed facts into rules, examples, questions, and deferred items with Example Mapping, and derive the packet's Expected Behavior and Validation (Example Mapping may lead only for the already-understood subset) |
+| Bridging to spec | **map-cc-sdd** | Convert the chosen packet into cc-sdd's Project Description / design and tasks hints |
+
+The details of each algorithm are in the corresponding skill's `rules/algo-*.md` (map-cc-sdd is in `rules/map-cc-sdd.md`). This mode definition is the combination table of "which phase uses which".
+
+## Application in each command
+
+### intent-discover (GORE-lite)
+- L0: why it exists. 1–2 sentences.
+- L1: whose state / what state to change and how (user/business/operations/developer experience).
+- L2: capabilities supporting L1. Write as responsibilities, not feature names.
+- L3: behavior / design intent that makes L2 hold (boundaries, dependency direction, side effects, consistency, UX constraints).
+- L4: candidate work units just before implementation. Above an Issue, before a spec.
+- For targets where the spec or tests have been lost, the current behavior is not necessarily correct. Place L3 raised from observation as inferred (guessed = Assumptions), not canonical (confirmed), and never mix it with confirmed intent.
+- Put branches where "it is unclear whether the current behavior is correct" into Open Questions as seeds for QOC, and corroborate them later by observing with Characterization Test.
+
+### intent-compass (QOC)
+- Draw the North Star from the Intent Tree.
+- Each Decision Rule is condensed as a lightweight ADR: Context (the question and situation) / Decision (the option taken) / Why (criteria) / Consequences (connection to Invariants and Anti-direction). QOC is the exploration tool for comparing options; the Decision Rule is the canonical record that binds future implementation sessions.
+- Anti-direction must always explicitly enumerate the local optimizations Claude tends to make. In particular, call out the tendency to "assume unverified behavior is correct and change it".
+- Invariants are behavior/API/data/UX/operational constraints that must not be broken. Distinguish them into two layers: project-universal / packet-specific. For targets with unknown behavior, only promote to an Invariant the behavior that has first been observed and confirmed with Characterization Test.
+
+### intent-packets (Example Mapping + Characterization Test)
+- **Execution order (important)**: for a target with unknown behavior, you cannot write "examples" for behavior you do not know. So run **Characterization Test first** to observe and lock the raw current behavior, then feed those observed facts into **Example Mapping afterward** to organize them into rules, examples, questions, and deferred items. Only for the subset of behavior you already understand may Example Mapping lead.
+- **How to route (routing)**: if a behavior can already be articulated as a rule, use Example Mapping; if it can only be pinned empirically (the spec has been lost and there is no certainty), use Characterization Test. Both handle observable behavior; the deciding axis is "can it be articulated vs. must it be pinned".
+- Characterization Test (first):
+  - Feed in the current code, observe "this is how it works now", and lock it as an observation point as-is (defer the judgment of correctness; record the current state). Sort whether each behavior is intentional or accidental, and send anything that cannot be sorted to Open Questions.
+  - Use the observed current behavior as the starting point for the packet's Expected Behavior / Validation, and hold the unknown behavior as a regression safety net.
+- Example Mapping (afterward / known parts first):
+  - Rules: the rules the capability follows (derived from the characterization observations, or from already-known behavior)
+  - Examples: observable concrete scenarios → the packet's Expected Behavior
+  - Questions: undetermined → the packet's Open Questions / sent back to the Compass
+  - Deferred: what you decided not to do this time → record it in the `Deferred` section of `.intent/packets/plan.md` rather than silently dropping it; the seed of a follow-up packet / Open Questions
+- Derive Validation (tests/manual/type/logs) and Rollback from the examples and the characterization observation points.
+- Packets satisfy testable / rollbackable; the count is variable with the expected change size, with 1–7 as a loose guide (one is fine for very small changes; do not pad the count). Leave a reference to the parent intent and to the observation points locked by characterization in each packet. Here **behavior-preserving means "preserve the current behavior fixed by characterization as the regression baseline"**, not a claim that the current behavior is correct (fixing wrong behavior is stated separately as its own intent).
+
+### intent-export-cc-sdd (map-cc-sdd)
+- Convert one packet into cc-sdd's Project Description (condensed) and design/tasks hints.
+- Limit the input to the target packet and the Compass's Invariants/Anti-direction.
+- Always leave references to parent intent and invariants in the tasks hints.
+
+## Applicable situations
+- When the target is legacy code whose behavior is unknown
+- When there are no or few tests, lacking a safety net that guarantees the current behavior
+- When the spec / design intent has been lost and behavior can only be raised from observing the code
+- When it is unclear whether the current behavior is correct, and you want to pin down "how it works now" first before structuring the intent
+- **Distinguishing from refactor**: if the current behavior is known and trusted (you can articulate the intended design), use refactor. If the current behavior is unknown or untrusted and you must start by observing and pinning it down, use behavior-unknown.

package/templates/en/intent/modes/feature-growth.md

@@ -0,0 +1,57 @@
+# Mode: feature-growth
+
+The mode for safely adding new features to an existing, running system. It inventories and protects the existing boundaries and contracts the new feature touches before implementation, establishes the seam first, and then stacks the feature additively — growing the feature while preserving the existing architectural boundaries.
+
+## The algorithms this mode combines
+
+| Phase | Algorithm | Purpose |
+|---|---|---|
+| Intent Tree construction | **GORE-lite** (lightweight Goal-Oriented Requirements Engineering) + **Impact Analysis** | Progressively decompose the goal into L0(purpose)→L1(outcomes)→L2(capabilities)→L3(behavior/architectural intent)→L4(candidate packets), appending the new feature's intent to the existing Intent Tree. Then inventory by reading which existing boundaries, contracts, and data flows the new feature touches, and raise the impact list (boundary touched / existing contract depended on / kind of impact) |
+| Recording decisions | **QOC** (Questions-Options-Criteria) | Preserve design decisions as "question, options, selection criteria" and flow them into the Compass's Decision Rules / Open Questions |
+| Concretizing behavior / packet decomposition | **Example Mapping** + **Additive Slicing** | Ground the new feature's behavior into observable concrete examples (rules, examples, questions, deferred), decompose it into the three-stage additive slices of establish the seam → add → wire, and derive the packet's Expected Behavior and Validation |
+| Bridging to spec | **map-cc-sdd** | Convert the chosen packet into cc-sdd's Project Description / design and tasks hints |
+
+The details of each algorithm are in the corresponding skill's `rules/algo-*.md` (map-cc-sdd is in `rules/map-cc-sdd.md`). This mode definition is the combination table of "which phase uses which".
+
+## Application in each command
+
+### intent-discover (GORE-lite + Impact Analysis)
+- Start by writing one **simplified Impact Mapping** (Adzic: the one-way tree of Why→Who→How→What) and confirm the connection between the feature addition and the business outcome before moving to GORE-lite. Feature additions tend to lead with "what to build (What)", severing the Why. Deepen the confirmed Impact hierarchy directly into GORE-lite's L0–L2: Why into L0/L1 (purpose, outcomes), Who/How into L1 (whose state / what state to change and how), What into the seeds of candidates at L2 and below.
+- With GORE-lite, **append** the new feature's intent to the existing Intent Tree (an incremental update). If no tree exists yet, raise L0–L4 for the scope of the new feature.
+- L0: why it exists. 1–2 sentences.
+- L1: whose state / what state to change and how (user/business/operations/developer experience).
+- L2: capabilities supporting L1. Write as responsibilities, not feature names.
+- L3: behavior / design intent that makes L2 hold (boundaries, dependency direction, side effects, consistency, UX constraints).
+- L4: candidate work units just before implementation. Above an Issue, before a spec.
+- Then, with Impact Analysis, inventory by reading which existing boundaries, contracts, and data flows the new feature touches, and produce the impact list (each item: boundary touched / existing contract depended on / kind of impact, with evidence; details in `algo-impact-analysis.md`). The impact list becomes the input for the Invariants in compass and for the seam design in packets.
+- Never mix canonical (confirmed) and inferred (guessed = Assumptions).
+- **When you find drift, do not fix it**: if, during the investigation, you discover a structural problem in the existing design (drift: a problem outside feature-growth's purpose), do not fix it within this mode; record it in Open Questions and recommend separate work in refactor mode.
+
+### intent-compass (QOC)
+- Draw the North Star from the Intent Tree.
+- Raise each boundary in the impact list into an Invariant ("do not change X's existing contract"). Invariants are behavior/API/data/UX/operational constraints that must not be broken. Distinguish them into two layers: project-universal / packet-specific.
+- Anti-direction must always explicitly enumerate the local optimizations Claude tends to make. Enumerate the feature-growth-specific patterns as a premortem (anticipating failures up front): "refactoring existing code while you're at it", "embedding directly into existing modules without creating a seam", and "rewriting existing tests to make things add up".
+- Each Decision Rule is condensed as a lightweight ADR: Context (the question and situation) / Decision (the option taken) / Why (criteria) / Consequences (connection to Invariants and Anti-direction). QOC is the exploration tool for comparing options; the Decision Rule is the canonical record that binds future implementation sessions.
+
+### intent-packets (Example Mapping + Additive Slicing)
+- Concretize the new feature's behavior with Example Mapping:
+  - Rules: the rules the capability follows
+  - Examples: observable concrete scenarios → the packet's Expected Behavior
+  - Questions: undetermined → the packet's Open Questions / sent back to the Compass
+  - Deferred: what you decided not to do this time → record it in the `Deferred` section of `.intent/packets/plan.md` rather than silently dropping it; the seed of a follow-up packet / Open Questions
+- **Input contract (important)**: Additive Slicing **takes as input the impact list** produced by Impact Analysis in the discover phase. A thin impact list turns the slices into guesswork — if it lacks the depth to design the seams, go back to discover and thicken the impact list.
+- With Additive Slicing, decompose the new feature — with the Example Mapping examples flowing in — into the three-stage additive slices of "establish the seam → additively stack the new feature → wire it into the existing system" (details in `algo-additive-slicing.md`).
+- **Impact-list traceability (required)**: every item in the impact list must terminate as one of — "protected by the Safety / Invariants of some slice" or "sent to Open Questions". Never silently drop an item.
+- Derive Validation (tests/manual/type/logs) and Rollback from the examples, and attach a Toggle Plan to each packet (which scope is off-by-default / under what condition the toggle gets removed).
+- Packets satisfy behavior-preserving / testable / rollbackable; the count is variable with the expected change size, with 1–7 as a loose guide (one is fine for very small changes; do not pad the count). Leave a reference to the parent intent in each packet (and the original item if it protects an impact-list item).
+
+### intent-export-cc-sdd (map-cc-sdd)
+- Convert one packet into cc-sdd's Project Description (condensed) and design/tasks hints.
+- Limit the input to the target packet and the Compass's Invariants/Anti-direction.
+- Always leave references to parent intent and invariants in the tasks hints.
+
+## Applicable situations
+- When adding a new feature to an existing, running system (extend / integrate / add-to style requests)
+- When the target's behavior is known and redesign (resolving drift) is not the goal
+- When you want to systematically inventory and protect the boundaries you touch, so new work does not break the existing architectural boundaries and dependency directions
+- **Distinguishing from standard / refactor / behavior-unknown**: if you want to change the existing structure (resolving drift / redesign is the goal), use refactor. If the current behavior itself is unknown and must first be observed and pinned down, use behavior-unknown. For a new product or general intent organization, use standard. If the goal is adding onto an existing system, use feature-growth.

package/templates/en/intent/modes/non-code.md

@@ -0,0 +1,46 @@
+# Mode: non-code
+
+The mode for working out the intent of non-program deliverables (documents, business processes, research/decisions, and so on). Without assuming code as the deliverable, it treats non-executable artifacts — prose, procedures, decisions — as the deliverable and progressively decomposes and concretizes their intent. It owns only the how-to-elaborate axis; the final output format (target format) is owned by a separate axis (format), so this mode definition does not specify output formatting.
+
+## The algorithms this mode combines
+
+The combination table for how to elaborate (how-to-elaborate) the intent of non-program deliverables (documents, business processes, research/decisions). It reuses the same foundational algorithms as standard, only re-reading the Purpose column for non-program deliverables (documents, business, research). It adds no new algo rule files (reuse).
+
+| Phase | Algorithm | Purpose |
+|---|---|---|
+| Intent Tree construction | **GORE-lite** (lightweight Goal-Oriented Requirements Engineering) | Progressively decompose the goal into L0(purpose)→L1(outcomes)→L2(capabilities)→L3(behavior/architectural intent)→L4(candidate packets). Here "capabilities/behavior" are re-read not as implementation but as the content, flow, and points-of-decision that non-executable artifacts — prose, procedures, decisions — must satisfy |
+| Recording decisions | **QOC** (Questions-Options-Criteria) | Preserve design decisions as "question, options, selection criteria" and flow them into the Compass's Decision Rules / Open Questions. For non-program cases, record decisions of "how to write / how to proceed / what to decide" |
+| Concretizing the deliverable | **Example Mapping** | Ground abstract capabilities into observable concrete examples (rules, examples, questions, deferred) and derive the packet's Expected Behavior and Validation. For non-program deliverables, treat "observable" as decidable by acceptance criteria (examples whose pass/fail is clear on reading) |
+| Bridging to spec | **map-cc-sdd** | Convert the chosen packet into cc-sdd's Project Description / design and tasks hints (the export path; projection into a non-program target format is owned by the format axis) |
+
+The details of each algorithm are in the corresponding skill's `rules/algo-*.md` (map-cc-sdd is in `rules/map-cc-sdd.md`). This mode definition is the combination table of "which phase uses which". It introduces no new algo and reuses the existing algorithms for non-program deliverables.
+
+## Application in each command
+
+### intent-discover (GORE-lite)
+- L0: why this deliverable (document, business process, research/decision) is needed. 1–2 sentences.
+- L1: whose state / what state to change and how (readers / business / decision-making / building consensus).
+- L2: the responsibilities of the deliverable that support L1. Write it as "what it must satisfy", not as a chapter list or feature name.
+- L3: the content, flow, and points-of-decision that make L2 hold (coverage, order, premises, consistency, reader constraints).
+- L4: candidate units of work before fair-copy (the chapters to write / procedures to work out / points to decide).
+- Never mix canonical (settled) with inferred (Assumptions).
+
+### intent-compass (QOC)
+- Draw the North Star from the Intent Tree.
+- Condense each Decision Rule as a lightweight ADR: Context / Decision / Why / Consequences. For non-program cases, preserve decisions of "how to write / how to proceed / what to decide" as the binding canonical record.
+- Invariants are the content / agreements / formatting / operational constraints you must not break (do not break the meaning or agreements of existing deliverables). Distinguish the two layers: project-wide / packet-specific.
+
+### intent-packets (Example Mapping)
+- Run Example Mapping for each L2/L3 capability (rules, examples, questions, deferred). Examples become the packet's Expected Behavior, questions become Open Questions, deferred goes into the Deferred section of `.intent/packets/plan.md`.
+- For non-program deliverables, degrade and re-read the Validation/Rollback vocabulary from its code-assuming form (testable→decidable by acceptance criteria / rollback→version control and revert / behavior-preserving→do not break the meaning or agreements of existing deliverables). This re-reading is an optional degrade and does not make the code-assuming vocabulary mandatory. Refer to the packet-format side for the definition of the re-read vocabulary; do not redefine it here.
+- Do not skip the packets stage; keep seeding the decision slots.
+
+### intent-export-cc-sdd (map-cc-sdd)
+- Convert one packet into cc-sdd's Project Description (condensed) and design/tasks hints. Limit the input to the target packet and the Compass's Invariants/Anti-direction.
+- Projection into a readable non-program deliverable format is owned not by this mode (how to elaborate) but by the format axis (target format).
+
+## Applicable situations
+
+- When you want to articulate the intent of a non-code deliverable (documents, specifications, business processes, procedures, records of research/decisions, and so on)
+- When you want to decompose and work out "what to write / how to proceed / what to decide" rather than "what to implement"
+- When code-assuming modes such as standard do not fit the deliverable — i.e., non-program cases

package/templates/en/intent/modes/refactor.md

@@ -0,0 +1,56 @@
+# Mode: refactor
+
+The mode for refactoring or redesigning an existing large-scale project while preserving behavior. It captures the drift between design intent and implementation and turns it into safe migration slices.
+
+## The algorithms this mode combines
+
+| Phase | Algorithm | Purpose |
+|---|---|---|
+| Intent Tree construction | **GORE-lite** (lightweight Goal-Oriented Requirements Engineering) + **Intent Recovery** (intent-less code only) + **Drift Analysis** | Progressively decompose the goal into L0(purpose)→L1(outcomes)→L2(capabilities)→L3(behavior/architectural intent)→L4(candidate packets). For code written without recording intent (e.g., vibe coding), use Intent Recovery to back-derive candidate intent from the code first, then observably capture the drift between the current implementation and the intended design |
+| Recording decisions | **QOC** (Questions-Options-Criteria) | Preserve design decisions as "question, options, selection criteria" and flow them into the Compass's Decision Rules / Open Questions |
+| Concretizing behavior / packet decomposition | **Migration Slicing** | Decompose the diff between the intended design and the current state into behavior-preserving / testable / rollbackable migration slices, and derive the packet's Expected Behavior and Validation |
+| Bridging to spec | **map-cc-sdd** | Convert the chosen packet into cc-sdd's Project Description / design and tasks hints |
+
+The details of each algorithm are in the corresponding skill's `rules/algo-*.md` (map-cc-sdd is in `rules/map-cc-sdd.md`). This mode definition is the combination table of "which phase uses which".
+
+## Application in each command
+
+### intent-discover (GORE-lite + Intent Recovery + Drift Analysis)
+- Build L0–L4 with GORE-lite. In particular, carefully articulate L3 (behavior / design intent) as the implicit intent of the existing implementation.
+- L0: why it exists. 1–2 sentences.
+- L1: whose state / what state to change and how (user/business/operations/developer experience).
+- L2: capabilities supporting L1. Write as responsibilities, not feature names.
+- L3: behavior / design intent that makes L2 hold (boundaries, dependency direction, side effects, consistency, UX constraints).
+- L4: candidate work units just before implementation. Above an Issue, before a spec.
+- **For code written without recording intent (e.g., vibe coding)**, insert Intent Recovery before Drift Analysis. Back-derive candidate intent from the code's structure and behavior, and place it all as inferred (guessed) — do not mix it with the confirmed side. Without this, no baseline for the "intended design" exists and Drift Analysis spins its wheels. Intent Recovery is unnecessary for code where intent is explicitly present.
+- Then, with Drift Analysis, inventory the current structure, dependency direction, and behavior, compare them against each L3 (the recovered inferred intent when Intent Recovery was applied), and enumerate the drift as "this is how it is now → this is how it should be". Do the matching with a Reflexion worksheet (intended responsibility/dependency vs. observed responsibility/dependency), classifying each element as convergence / divergence / absence (details in `algo-drift-analysis.md`).
+- Distinguish each drift by type — deviation / decay / accumulation of local optimizations — and link it to the corresponding parent intent (L1/L2/L3).
+- Never mix canonical (confirmed) and inferred (guessed = Assumptions). Send drift whose linked intent is ambiguous to Open Questions.
+
+### intent-compass (QOC)
+- Draw the North Star from the Intent Tree.
+- Each Decision Rule is condensed as a lightweight ADR: Context (the question and situation) / Decision (the option taken) / Why (criteria) / Consequences (connection to Invariants and Anti-direction). QOC is the exploration tool for comparing options; the Decision Rule is the canonical record that binds future implementation sessions.
+- Anti-direction must always explicitly enumerate the local optimizations Claude tends to make. As refactor-specific examples, at minimum call out "touching unrelated code while fixing drift (scope creep)" and "changing behavior under the guise of being behavior-preserving".
+- Invariants are behavior/API/data/UX/operational constraints that must not be broken. Distinguish them into two layers: project-universal / packet-specific. For refactoring, explicitly call out the existing behavior that must be preserved during migration.
+
+### intent-packets (Migration Slicing)
+- **Input contract (important)**: Migration Slicing **takes as input the drift list** produced by Drift Analysis in the discover phase. A thin or vague drift list makes the slices guesswork and lowers their quality. Before cutting slices, verify that the drift list is sufficient; if not, go back to discover and thicken the drift list.
+- Before cutting slices, run a **Mikado pre-pass** (Mikado Method = finding a safe change order by back-calculating prerequisites): back-calculate "what must be true first for this to be changed safely", write the prerequisite graph, and start from the leaves that have no prerequisites (a desk back-calculation — no experimental code changes; details in `algo-migration-slicing.md`).
+- Cut the diff between the intended design and the current state (the drift list) into the smallest migration slices that can be applied without breaking behavior.
+- Each slice must be independently deployable and advance the design one step while preserving the existing behavior.
+- Order the slices by dependency so that each slice unblocks the next. Confirm that the intermediate state stays consistent (behavior-preserving) wherever you stop.
+- Attach to each slice characterization / regression checkpoints (Validation) and a way to roll back on failure (Rollback) (you may reuse the observe-and-pin procedure from `intent-packets/rules/algo-characterization-test.md`).
+- **Drift traceability (required)**: every enumerated drift must terminate in one of two ways — (a) become a migration slice (packet), or (b) if not addressed this time, become an Open Question or an explicit deferral (with a reason). Never silently drop a drift you have found (this is the core of the North Star: do not leave the accumulation of local optima ignored).
+- Packets satisfy behavior-preserving / testable / rollbackable; the count is variable with the expected change size, with 1–7 as a loose guide (one is fine for very small changes; do not pad the count). Leave a reference to the parent intent in each packet (and the originating drift if it came from drift).
+
+### intent-export-cc-sdd (map-cc-sdd)
+- Convert one packet into cc-sdd's Project Description (condensed) and design/tasks hints.
+- Limit the input to the target packet and the Compass's Invariants/Anti-direction.
+- Always leave references to parent intent and invariants in the tasks hints.
+
+## Applicable situations
+- When the target is refactoring or redesigning an existing large-scale project
+- When the existing codebase is large and drift between design intent and implementation has accumulated
+- When you want to advance the design incrementally while preserving behavior (behavior-preserving)
+- When you want to take code written without recording intent (vibe coding, a prototype pushed into production, etc.) into the intent system after the fact (combine with Intent Recovery in discover)
+- **Distinguishing from behavior-unknown**: if the current behavior is reasonably understood and you can articulate the intended design, use refactor. If the behavior itself is unknown and needs to be observed and pinned down first, use behavior-unknown. Vibe coding is often a case where "behavior is observable but intent is absent", for which refactor + Intent Recovery is the fit.