create-pathfinder 3.0.0 → 4.0.0

package/AGENTS.md

@@ -2,11 +2,11 @@
 
 Read `CLAUDE.md` first.
 
-Project truth lives in `context/`. Follow the technology and delivery choices documented in `context/project-overview.md`; do not assume a framework, package manager, branch model, or release process. That file, like `context/features/`, `context/history.md`, `context/current-feature.md`, and `context/handoff.md`, is created by the workflow that first needs it — its absence is normal, not an error. Track the durable ones in Git; `context/current-feature.md` and `context/handoff.md` are transient session state and belong in `.gitignore`. Never ignore `context/` as a whole.
+Project truth lives in `context/`. Follow the technology and delivery choices documented in `context/project-overview.md`; do not assume a framework, package manager, branch model, or release process. That file, like `context/features/`, `context/history.md`, `context/current-ticket.md`, and `context/handoff.md`, is created by the workflow that first needs it — its absence is normal, not an error. `context/tickets/` exists only when local Markdown is the project's ticket store; a project whose tickets are in GitHub Issues or another tracker has none, and that is not a gap. Track the durable ones in Git; `context/current-ticket.md` and `context/handoff.md` are transient session state and belong in `.gitignore`. Never ignore `context/` as a whole.
 
-Use the smallest relevant context for the active task. Keep each delivery chunk stable, reviewable, and verifiable.
+Use the smallest relevant context for the active task. Keep each ticket stable, reviewable, and verifiable.
 
-The roles are `planner`, `developer`, and `tester`. When the human names one, read `roles/<name>.md` before anything else and follow it for that session. A role is a declarative contract stating what a worker is responsible for and what it must not do, where a skill states how to perform a task. Naming one is the only thing that activates it, so a session where none is named behaves exactly as if `roles/` were not there.
+The roles are `planner`, `developer`, and `tester`. Lifecycle skills assume the responsible role for each invocation and read its contract themselves. When the human explicitly names a role, read `roles/<name>.md` before anything else and use it instead for that session. A role is a declarative contract stating what a worker is responsible for and what it must not do, where a skill states how to perform a task. Assumed or explicit, a role narrows responsibility and never grants human authority.
 
 Canonical skills live under `skills/` and are the only behavior contract; anything under `.claude/skills/` or `.agents/skills/` is a generated pointer to one, so edit the canonical file and regenerate the adapter.
 

package/CLAUDE.md

@@ -4,34 +4,41 @@ This repository uses an AI-assisted, human-in-the-loop workflow. Project truth l
 
 ## Read only what is needed
 
-For feature work, usually read:
+For delivery work, usually read:
 
-1. `context/current-feature.md`
-2. its referenced feature spec
+1. `context/current-ticket.md`
+2. the ticket it names, and that ticket's parent feature spec
 3. relevant sections of `context/project-overview.md`
 4. relevant rules from `context/coding-standards.md`
 5. `context/ai-interaction.md`
-6. only the source files needed for the current delivery chunk
+6. only the source files needed for the current ticket
 
 Do not load the whole repo by default.
 
 Pathfinder ships two context files: `ai-interaction.md` and
 `coding-standards.md`. Everything else in `context/` — `project-overview.md`,
-`features/`, `history.md`, `current-feature.md`, `handoff.md` — is written by
-the workflow that first needs it. A missing file here is normal; skip it rather
-than treating it as an error.
+`features/`, `tickets/`, `history.md`, `current-ticket.md`, `handoff.md` — is
+written by the workflow that first needs it. A missing file here is normal; skip
+it rather than treating it as an error. `tickets/` in particular exists only
+when local Markdown is the project's ticket store.
 
 Track the durable ones in Git and ignore the two transient ones,
-`current-feature.md` and `handoff.md`. `context/coding-standards.md` carries the
+`current-ticket.md` and `handoff.md`. `context/coding-standards.md` carries the
 rule; do not ignore `context/` wholesale.
 
 ## Roles
 
-When the human names a role, read `roles/<name>.md` before anything else and follow it for the session. A role says what a worker is responsible for, what it reads, and what it must not do, where a skill says how to perform a task.
+Lifecycle skills assume their responsible role for each invocation and read its
+contract themselves: planning uses `planner`, ticket implementation and
+completion use `developer`, and ticket review uses `tester`.
 
-The roles are `planner`, `developer`, and `tester`. Activate one with `/role <name>`.
+The human can explicitly override that default with `/role <name>`. Read the
+named `roles/<name>.md` before anything else and follow it for the session. A
+role says what a worker is responsible for, what it reads, and what it must not
+do, where a skill says how to perform a task.
 
-Naming a role is the only thing that activates one. If the human names none, ignore `roles/` and work as this guide otherwise describes. A role narrows what a session may do and never widens it. Human authority sits outside the role system: approval, acceptance, merge, and release are always the human's.
+A role narrows responsibility and never widens authority. Approval, acceptance,
+merge, and release remain the human's whether a role was assumed or explicit.
 
 ## Project-selected policies
 
@@ -44,7 +51,7 @@ If a policy is `TBD`, do not invent it. Ask the human or clearly mark it unresol
 Restate:
 
 1. Goal
-2. Active delivery chunk
+2. Active ticket
 3. Expected files or areas
 4. Required context
 5. Risks
@@ -60,8 +67,8 @@ Ask before actions identified in `context/ai-interaction.md`, especially depende
 
 ## Scope and quality
 
-- Implement only the active feature and current delivery chunk.
-- Keep the project stable after each chunk.
+- Implement only the active feature and current ticket.
+- Keep the project stable after each ticket.
 - Do not convert prototype code into production code without an explicit feature decision.
 - Prefer concrete verification over confident narration.
 - Report conflicts between specs, repository reality, and durable context.
@@ -70,6 +77,8 @@ Ask before actions identified in `context/ai-interaction.md`, especially depende
 
 Canonical Pathfinder skills are tool-neutral and live under `skills/`. Harness-specific representations — `.claude/skills/`, `.agents/skills/` — are generated integration artifacts and must not become independent behavior contracts. Edit the canonical file; regenerate the adapter.
 
+The Claude Code plugin declared by `.claude-plugin/plugin.json` is a third discovery surface, and the only one that generates nothing: it exposes the canonical `skills/` tree itself, namespaced `/pathfinder:<skill>`. There is no plugin copy of any skill and there must never be one. If a discovery surface and its canonical skill disagree, the canonical skill is correct.
+
 An adapter carries the canonical skill's frontmatter and a pointer to it, and nothing else. If an adapter and its canonical skill disagree, the canonical skill is correct.
 
 ## Available skills
@@ -79,7 +88,8 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `reverse-engineer` — analyze an external reference and produce an evidence-based reconstruction blueprint
 - `prototype` — create and iterate the cheapest useful validation artifact
 - `to-specs` — generate context-sized feature specs
-- `feature` — run one action of the Feature delivery loop: `load`, `start`, `review`, `complete`
+- `to-tickets` — decompose one approved Feature into blocker-linked tickets
+- `ticket` — run one action of the ticket delivery loop: `load`, `start`, `review`, `complete`
 - `debug-issue` — diagnose an observed failure to its root cause, apply the smallest justified fix, and verify it
 - `learn-feature` — create an interactive lesson for a completed feature
 - `learn-codebase` — create a modular learning portal for the repository
@@ -90,8 +100,7 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `learning-review` — review accumulated lessons, identify gaps, and create a reinforcement plan
 - `reflect` — review completed work, and the reflection itself, and propose reusable workflow improvements for human approval
 - `handoff` — preserve useful state between sessions or tools
-- `role` — activate one named role for the current session
+- `role` — explicitly override the role the lifecycle would assume
 - `whereami` — report a compact read-only snapshot of the current session
 - `skillsmith` — teach and create small local skills
-- `setup-tracker` — configure an optional external work tracker
-- `sync-tracker` — publish approved feature specs to the configured tracker, one-way and idempotently
+- `setup-tracker` — choose the canonical ticket store when it is not local Markdown

package/README.md

@@ -80,11 +80,11 @@ The installer copies six kit entries into your repository:
 | --- | --- |
 | `AGENTS.md`, `CLAUDE.md` | Entry files that tell supported agents how to work in the project |
 | `context/` | Project standards and interaction rules; other context is created only when needed |
-| `roles/` | Three optional responsibility contracts: planner, developer, tester |
-| `skills/` | Reusable procedures for discovery, specs, delivery, debugging, review, learning, and optional work tracking |
+| `roles/` | Planner, developer, and tester contracts assumed by lifecycle skills |
+| `skills/` | Reusable procedures for discovery, specs, delivery, debugging, review, learning, and ticket-store selection |
 | `templates/` | Minimal starting shapes; records are created from them later, when a workflow needs one |
 
-A fresh Pathfinder 2.0 project begins with only:
+A fresh Pathfinder project begins with only:
 
 ```text
 context/
@@ -261,6 +261,23 @@ Pathfinder also never writes to personal/global skill directories such as:
 ~/.agents/skills/
 ```
 
+### The Claude Code plugin is a separate path
+
+Pathfinder is also distributed as a Claude Code plugin, installed with
+`/plugin marketplace add rikilamadrid/pathfinder` followed by
+`/plugin install pathfinder@lamadrid-labs`. It does not replace this installer
+and does not change anything it does.
+
+The two install different things. The plugin installs commands, always
+namespaced `/pathfinder:<skill>`, into your Claude Code installation and writes
+nothing into your repository — no kit, no adapters. This installer copies the
+kit your repository keeps under version control, and generates the adapters that
+expose the bare `/<skill>` names.
+
+A repository can have both, and then carries both command forms running the same
+canonical skill body. If you arrived through the plugin with no kit yet,
+`/pathfinder:kickstart-pathfinder` offers to install one for you.
+
 ### Interactive selection
 
 In an interactive terminal, the installer asks which supported tools to

package/context/ai-interaction.md

@@ -20,7 +20,7 @@ Ask before:
 - Git history rewriting
 - commits, merges, releases, or deployments
 - adopting prototype code into production
-- writes outside the repository, such as shared tracker changes
+- writes outside the repository, such as tickets in a shared store
 
 The human owns judgment, acceptance, merge, and release decisions.
 
@@ -34,21 +34,24 @@ or deployment workflow.
 Inspect current Git state before acting. If the workflow is unclear or
 `TBD`, ask.
 
-## Feature Workflow
+## Delivery Workflow
 
 Use the workflow skills instead of recreating their procedures in chat:
 
-1. `/feature load` — load the active work and relevant context.
-2. `/feature start` — implement the current delivery chunk.
-3. `/feature review` — verify the work and report findings.
-4. `/feature complete` — complete accepted work and durable records.
-5. `learn-feature` — optionally teach what was implemented.
+1. `to-tickets` — slice one approved Feature into executable tickets.
+2. `/ticket load` — load one ticket, its Feature, and relevant context.
+3. `/ticket start` — implement that ticket.
+4. `/ticket review` — verify the work and report findings.
+5. `/ticket complete` — complete accepted work and durable records, and name
+   the tickets that are now ready.
+6. `learn-feature` — optionally teach what was implemented.
 
-Roles are optional. The workflow must work without activating one.
+Lifecycle skills assume their responsible role automatically. Explicit
+activation with `/role` is optional and overrides that default for the session.
 
 ### Status
 
-Feature status records durable lifecycle state only:
+Ticket status records durable lifecycle state only:
 
 `Proposed` → `Ready` → `In Progress` → `Complete`
 
@@ -56,17 +59,20 @@ Feature status records durable lifecycle state only:
 
 - `Ready` means the human approved execution.
 - Review and testing are optional workflow activity, not a status.
-  A Feature stays `In Progress` until it is complete.
-- `Blocked` is not a status; record the blocker in current workspace state.
+  A ticket stays `In Progress` until it is complete.
+- `Blocked` is not a status. A ticket's blockers are the edges under its
+  `## Blocked by`, and anything else that stops work is recorded in current
+  workspace state.
+- A Feature's status is derived from its tickets, never maintained by hand.
 - The human decides approval, acceptance, cancellation, and supersession.
 
 ## Context Discipline
 
 - Read only what the current work requires.
 - Prefer exact files or sections over broad repository scans.
-- Do not load history, roadmap, tracker data, or unrelated context by
+- Do not load history, roadmap, other tickets, or unrelated context by
   default.
-- Work one delivery chunk at a time.
+- Work one ticket at a time.
 - If the work can no longer be understood safely in a focused session,
   stop and split or hand off.
 - Extra scaffolding must earn its cost by reducing downstream context.

package/context/coding-standards.md

@@ -92,10 +92,12 @@ Keep durable truth in its appropriate project artifact.
   `context/project-overview.md`
 - Feature contracts:
   `context/features/`
+- executable tickets, when local Markdown is the configured store:
+  `context/tickets/`
 - completed outcomes:
   `context/history.md`
 - active workspace state:
-  `context/current-feature.md`
+  `context/current-ticket.md`
 - state handed to the next session:
   `context/handoff.md`
 
@@ -115,6 +117,7 @@ project", it outlives any session, and a reviewer should see it change:
 ```text
 context/project-overview.md
 context/features/
+context/tickets/ # only when local Markdown is the ticket store
 context/history.md
 context/tracker.md
 ```
@@ -124,14 +127,14 @@ it belongs to one session on one machine, and committing it puts one person's
 in-flight work in everybody's diff:
 
 ```text
-context/current-feature.md
+context/current-ticket.md
 context/handoff.md
 ```
 
 Two lines in `.gitignore` are the whole mechanism:
 
 ```text
-context/current-feature.md
+context/current-ticket.md
 context/handoff.md
 ```
 
@@ -144,7 +147,8 @@ A team that would rather share workspace state — a single-machine project, or
 handoff meant to be read by a colleague — can track them instead. Nothing in the
 kit reads Git state to decide how to behave.
 
-`context/tracker.md` is durable and tracked, with one exception that does not
-apply to your project: Pathfinder's own repository ignores it, because `context`
-is a directory in the installer's copy list and a committed copy would ship
-Pathfinder's tracker config to every new install.
+`context/tracker.md` is durable and tracked when the project selects a store
+other than local Markdown. With local Markdown, `context/tickets/` is durable
+and tracked instead. Pathfinder's own repository ignores its tracker config,
+because `context` is a directory in the installer's copy list and a committed
+copy would ship Pathfinder's store selection to every new install.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-pathfinder",
-  "version": "3.0.0",
-  "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
+  "version": "4.0.0",
+  "description": "Install Pathfinder's ticket-first, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",
     "ai",

package/roles/developer.md

@@ -17,7 +17,8 @@ Do not load unrelated history, roadmap, Features, or repository areas by default
 
 ## Use
 
-- `feature` — its load action to load the work, its start action to implement it.
+- `ticket` — its load action to load work, start action to implement it, and
+  complete action to record work the human accepted.
 - Use the project's existing build, test, and verification commands as needed.
 
 ## Rules

package/roles/planner.md

@@ -1,14 +1,14 @@
 ---
 name: planner
-description: Turns approved direction into small, implementable Feature specs.
+description: Discovers project direction and turns it into implementable Features and tickets.
 ---
 
 # Planner
 
 ## Responsibility
 
-Turn approved direction into clear Feature specs for another session to
-implement.
+Discover project direction, turn approved direction into clear Feature specs,
+and slice those Features into tickets another session can implement.
 
 ## Context
 
@@ -18,8 +18,10 @@ Inspect implementation code only when necessary to understand the work.
 
 ## Use
 
+- `kickstart-pathfinder` to discover and initialize project context.
 - `debate-me` when direction still needs pressure-testing.
 - `to-specs` to create Feature specs.
+- `to-tickets` to slice one approved Feature into executable tickets.
 
 ## Rules
 
@@ -33,6 +35,6 @@ Inspect implementation code only when necessary to understand the work.
 
 ## Finish
 
-Produce the Feature specs and clearly identify any unresolved human decisions.
-
-Stop before implementation.
+Finish at the invoked skill's stop condition: approved project context, Feature
+specs, or a ticket graph. Identify unresolved human decisions and stop before
+implementation.

package/roles/tester.md

@@ -20,7 +20,7 @@ Do not rely on the developer's summary as proof.
 
 ## Use
 
-- `feature` — its review action, to verify implemented work.
+- `ticket` — its review action, to verify implemented work.
 - Use the project's existing test commands and relevant testing tools.
 
 ## Rules

package/skills/debug-issue/SKILL.md

@@ -29,9 +29,9 @@ Use Debug Issue when there is a concrete unexpected behavior such as:
 
 Do not use it merely because implementation work is difficult.
 
-If the task is planned feature construction, use `/feature start`.
+If the task is planned construction, use `/ticket start`.
 
-If the goal is reviewing completed implementation for possible defects, use `/feature review`.
+If the goal is reviewing completed implementation for possible defects, use `/ticket review`.
 
 If the real question is broad understanding of the repository, use `learn-codebase`.
 
@@ -202,8 +202,8 @@ It does not:
 
 * implement unrelated feature scope
 * perform a general repository review
-* replace `/feature review`
-* replace `/feature complete`
+* replace `/ticket review`
+* replace `/ticket complete`
 * silently change architecture or dependencies
 * turn debugging into opportunistic refactoring
 * hide uncertainty behind a successful-looking workaround

package/skills/kickstart-pathfinder/SKILL.md

@@ -7,6 +7,12 @@ description: Discover and initialize a new or existing project without writing p
 
 Use this skill to turn an idea or existing repository into durable, human-approved project context.
 
+## Assumed role
+
+Unless the human explicitly activated a role, assume `planner` for this
+invocation: read `roles/planner.md` and follow it. An explicit role overrides
+this default. A role narrows responsibility and never grants human authority.
+
 ## Rules
 
 - Do not install packages or write product code.
@@ -36,18 +42,57 @@ When the user is unsure, provide a small recommendation with reasoning and alter
 
 ## Process
 
-1. Read the kit context and inspect relevant repository facts.
-2. Ask the minimum unresolved questions in small groups.
-3. Summarize requirements, preferences, constraints, open decisions, and contradictions.
-4. Route uncertain product/technical choices to `debate-me` when useful.
-5. Present the proposed context and request human corrections or approval.
-6. Update `context/project-overview.md`, `context/coding-standards.md`, `context/ai-interaction.md`, `CLAUDE.md`, and `AGENTS.md` only after the choices are sufficiently clear.
+1. If the project is missing kit files, and this session loaded this skill from
+   the Pathfinder plugin, offer to install the kit before going further. See
+   `Kit Bootstrap` below. Otherwise start at the next step.
+2. Read the kit context and inspect relevant repository facts.
+3. Ask the minimum unresolved questions in small groups.
+4. Summarize requirements, preferences, constraints, open decisions, and contradictions.
+5. Route uncertain product/technical choices to `debate-me` when useful.
+6. Present the proposed context and request human corrections or approval.
+7. Update `context/project-overview.md`, `context/coding-standards.md`, `context/ai-interaction.md`, `CLAUDE.md`, and `AGENTS.md` only after the choices are sufficiently clear.
    `context/project-overview.md` does not ship; create it from `templates/project-overview.template.md` at this step.
    Project facts go there; approval rules and tool actions requiring a human go
    in `context/ai-interaction.md`. Fill the sections the project has and mark
    the rest `TBD` or `None`. Do not add sections the template does not carry,
    and do not leave a field blank.
-7. Recommend `debate-me`, `prototype`, or `to-specs` as the next action.
+8. Recommend `debate-me`, `prototype`, or `to-specs` as the next action.
+
+## Kit Bootstrap
+
+The Pathfinder plugin distributes commands. It does not distribute project
+state. A repository reached through `/plugin install` therefore has every
+Pathfinder command and none of the files those commands read.
+
+This step applies only when both are true: the project is missing kit files,
+and this skill was loaded from the plugin, which is what makes
+`${CLAUDE_PLUGIN_ROOT}` — the plugin's install directory — a real path. When
+the kit installed this skill into the repository instead, there is no plugin
+root, the condition is false, and this whole section is skipped without being
+raised or quoted.
+
+When it does apply:
+
+- Copy from the plugin root into the project root, and copy only the kit. That
+  list is not restated here: `packages/create-pathfinder/copy-list.json`, inside
+  the plugin root, is the one statement of it. Read that file and copy the
+  entries it names.
+- Exclude exactly what the installer excludes, and read that from the installer
+  too: `NEVER_SHIPS` in `packages/create-pathfinder/src/kit.mjs`, also inside
+  the plugin root, is the one statement of it. Skip every kit-relative path it
+  holds. Those files are one repository's own working state and would be wrong
+  in any other project. Restating them here would be a second list to keep in
+  step, and the first time it drifted this step would hand a project what
+  `npx create-pathfinder` refuses to.
+- Name every file before writing it, and wait for approval.
+- Overwrite nothing without asking about that file by name. Delete nothing.
+- Report exactly what was written, what was skipped, and what was left alone.
+- Generate no harness adapters. Plugin commands stay namespaced
+  `/<plugin-name>:<skill>`, and that is the intended plugin form.
+  `npx create-pathfinder --agents claude-code` is what generates adapters and
+  the bare command names, for a human who wants both.
+
+When the project already has the kit, change nothing and say so.
 
 ## Stop Condition
 

package/skills/quiz-me/SKILL.md

@@ -13,7 +13,7 @@ The goal is retrieval and diagnosis, not entertainment and not a long exam.
 ## Read First
 
 1. The relevant lesson in `context/learning/lessons/`
-2. `context/current-feature.md`
+2. `context/current-ticket.md`
 3. Only the implementation or tests needed to verify answers
 4. `context/learning/progress.md`
 

package/skills/reverse-engineer/SKILL.md

@@ -173,7 +173,7 @@ Use one of these:
 * `debate-me` — when major product or technical decisions remain
 * `prototype` — when the experience or technical assumption needs validation
 * `to-specs` — when the direction is approved and ready to become feature files
-* `/feature load` — when the analysis applies to one already-planned feature
+* `/ticket load` — when the analysis applies to one already-planned ticket
 * `learn-codebase` — when the user wants to understand their own repository instead
 * no handoff — when the user only requested analysis
 

package/skills/role/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: role
-description: Activate one named Pathfinder role for the current session.
+description: Explicitly override the role Pathfinder's lifecycle would assume.
 argument-hint: planner|developer|tester
 ---
 
 # Role
 
-Activate exactly one role.
+Explicitly activate exactly one role for the current session.
+
+Normal lifecycle skills assume their responsible role automatically. Use this
+skill only when the human wants to override that default or inspect/debug work
+under a particular responsibility boundary.
 
 The human names it, for example:
 
@@ -27,6 +31,8 @@ The human names it, for example:
 ## Rules
 
 - Activate only the role the human named.
+- The explicit role overrides a lifecycle skill's automatic default for the
+  rest of the current session/conversation context.
 - Read only that role file.
 - Do not start the role's work.
 - Do not write project state just to remember the role.

package/skills/setup-tracker/SKILL.md

@@ -1,42 +1,62 @@
 ---
 name: setup-tracker
-description: Configure optional work tracking for the project.
+description: Choose the canonical ticket store when it is not local Markdown.
 ---
 
 # Setup Tracker
 
-Configure a work tracker only when the human asks.
+Configure a ticket store only when the human asks.
 
-Pathfinder works normally without one.
+Pathfinder works normally without one: with no configuration, tickets are local
+Markdown files under `context/tickets/`. That is already a store, and for many
+projects it is the right one. This skill is for projects whose tickets belong
+somewhere else instead.
 
 ## Process
 
-1. Ask where work should be tracked:
+1. Ask where tickets should live:
    - GitHub Issues
    - local Markdown files
-   - another tracker the human describes
-2. Ask only for the information needed to use that tracker.
-3. Check where the approved Feature specs live. Ask only when they are not in
-   `context/features/`; when the default is what the repository has, record it
-   and move on.
+   - another tracker the human describes — Jira, Linear, Azure DevOps, or
+     something internal
+2. Ask only for the information needed to use that store.
+3. Say plainly what the choice means: that store becomes the only place the
+   project's tickets exist. Moving to a different one later is a deliberate
+   human migration, and nothing moves tickets between stores automatically.
 4. Create a proposed `context/tracker.md` naming, at minimum:
-   - the tracker and how an agent reaches it
-   - the spec source
-   - how a published item records its Pathfinder key, so a later run
-     recognises the item it published last time
+   - the store and how an agent reaches it
+   - where tickets are within it, when that is a choice the store offers
+   - how a ticket carries its key, so a later run finds the ticket it created
 5. Show it to the human.
 6. Write it only after approval.
 
 If `context/tracker.md` already exists, modify only the requested settings.
 
+## The key
+
+A ticket's key is `NN.TT` — the parent Feature number and the ticket number
+within it. In the local Markdown store it is the filename. In any other store
+the config has to say what carries it: a marker in the item body, a recorded
+issue number, a field the tracker offers.
+
+Which one is the store's business. What the kit requires is only the property —
+a later session must be able to find the ticket by its key, because blocker
+edges name keys and nothing else.
+
+Ask for it explicitly. A config that cannot answer this is not finished.
+
 ## Rules
 
-- Do not publish or create work items.
+- Do not create tickets. This skill configures the store and nothing else.
 - Do not create labels, tags, or tracker conventions unless requested.
 - Do not add dependencies or tracker-specific code.
-- Feature specs remain canonical.
-- Tracking is always optional.
-
-Publishing belongs to `sync-tracker`.
+- The configured store is canonical. There is one ticket artifact, and no copy
+  of it in the repository.
+- Feature specs are not tickets. They stay in the repository whatever the store.
+- Configuration is always optional. Its absence selects the local Markdown
+  store, so never write a placeholder config.
+
+Creating and updating tickets belongs to `to-tickets` and the ticket lifecycle,
+not here.
 
 Stop after configuration.

package/skills/teach-feature/SKILL.md

@@ -13,7 +13,7 @@ The goal is not to produce generic documentation. The goal is to help the learne
 
 Read only the smallest useful context:
 
-1. `context/current-feature.md`
+1. `context/current-ticket.md`, and the ticket it names
 2. The source feature spec under `context/features/`
 3. `context/project-overview.md`
 4. The current branch, working tree status, and focused diff