create-pathfinder 1.7.0 → 2.0.0

package/context/ai-interaction.md

@@ -1,76 +1,116 @@
 # AI Interaction Guidelines
 
-This file defines how AI agents collaborate with the human owner. Project-specific choices override generic defaults when explicitly documented.
+This file defines the default rules for AI-assisted work.
+Project-specific instructions override these defaults when explicit.
 
 ## Communication
 
 - Be concise, direct, and honest.
-- Distinguish facts, recommendations, assumptions, and unresolved decisions.
+- Separate facts, assumptions, recommendations, and unresolved decisions.
 - Do not invent answers for `TBD` items.
-- Stop after 2–3 grounded failed approaches and explain the blocker.
+- After 2–3 grounded failed approaches, stop and explain the blocker.
 
-## Approval Boundaries
+## Human Approval
 
-Follow the project's documented policy. Unless explicitly pre-approved, ask before:
+Ask before:
 
-- dependencies or build-tool changes
-- architecture migrations
+- architecture or dependency changes
 - database, auth, payment, secrets, or security-sensitive changes
 - destructive commands or file deletion
 - Git history rewriting
 - commits, merges, releases, or deployments
 - adopting prototype code into production
+- writes outside the repository, such as shared tracker changes
+
+The human owns judgment, acceptance, merge, and release decisions.
 
 ## Git and Delivery
 
-Follow `context/project-overview.md`. Do not assume `main`, feature branches, Git Flow, conventional commits, pull requests, or SemVer.
+Follow `context/project-overview.md`.
 
-Before Git actions, inspect current state and state what the documented workflow requires. If the workflow is `TBD`, ask before changing it.
+Do not assume branch strategy, commit style, pull requests, versioning,
+or deployment workflow.
 
-## Feature Lifecycle
+Inspect current Git state before acting. If the workflow is unclear or
+`TBD`, ask.
 
-1. `load-feature` prepares one feature and checks context readiness.
-2. `start-feature` implements one delivery chunk at a time.
-3. `review-feature` reports findings against the spec and repository standards.
-4. `complete-feature` verifies acceptance criteria and updates durable records.
-5. `learn-feature` may generate an interactive lesson after completion.
+## Feature Workflow
 
-## Context Discipline
+Use the workflow skills instead of recreating their procedures in chat:
+
+1. `load-feature` — load the active work and relevant context.
+2. `start-feature` — implement the current delivery chunk.
+3. `review-feature` — verify the work and report findings.
+4. `complete-feature` — complete accepted work and durable records.
+5. `learn-feature` — optionally teach what was implemented.
+
+Roles are optional. The workflow must work without activating one.
+
+### Status
 
-- Read the active feature, its dependencies, and only relevant durable context.
-- Use the feature's Context Boundary and Delivery Chunks.
-- Avoid repo-wide scans unless the task genuinely requires them.
-- Split the feature when a focused session cannot safely understand, implement, and verify it.
-- Never hide excessive scope behind a long checklist.
+Feature status records durable lifecycle state only:
 
-## Prototype Workflow
+`Proposed` → `Ready` → `In Progress` → `Complete`
 
-- Use `debate-me` to determine whether prototyping is warranted.
-- Use `prototype` to validate one important assumption at a time.
-- Ask the human to approve, revise, replace, or stop the direction.
-- Record approved direction and rejected assumptions.
-- Do not treat prototype output as production-ready.
+`Cancelled` and `Superseded` are terminal alternatives.
+
+- `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.
+- 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
+  default.
+- Work one delivery chunk 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.
 
 ## Scope Control
 
-Do not drift into unrelated refactors, extra features, dependency swaps, broad visual changes, speculative abstractions, or later roadmap items.
+Stay inside the approved work.
+
+Do not add unrelated refactors, features, dependency changes, visual
+redesigns, speculative abstractions, or later roadmap work.
 
-## Review Priorities
+When necessary work falls outside scope, stop and ask.
 
-Use the project's quality priorities. When none are specified, review in this order:
+## Prototypes
+
+Use `debate-me` to decide whether a prototype is useful.
+
+Use `prototype` to test one important assumption at a time.
+
+Prototype output is evidence, not production code, until the human
+explicitly approves adoption.
+
+## Review
+
+Review against the Feature and the actual diff.
+
+Prioritize:
 
 1. correctness
-2. security/privacy
+2. security and privacy
 3. regressions and edge cases
-4. accessibility when applicable
+4. accessibility when relevant
 5. performance
 6. maintainability
-7. consistency
-8. polish
+
+Verification effort should be proportional to risk.
+
+Report findings; do not manufacture them.
 
 ## Learning
 
-- Explain what was actually implemented, not an idealized architecture.
-- Use diagrams, examples, and quizzes when they improve understanding.
-- Do not expose private chain-of-thought.
-- Keep feature lessons scoped; reserve broad repository scanning for `learn-codebase`.
+Explain what was actually implemented.
+
+Use examples, diagrams, or quizzes only when they improve understanding.
+
+Keep Feature learning scoped. Use `learn-codebase` for broad repository
+study.

package/context/coding-standards.md

@@ -1,91 +1,150 @@
 # Coding Standards
 
-These standards are stack-agnostic. Extend them after the project selects a real stack; remove sections that do not apply.
+These are stack-agnostic defaults.
+Project-specific conventions override them when explicit.
 
 ## Core Principles
 
 - Prefer readable, explicit code over clever code.
 - Keep modules cohesive and boundaries clear.
-- Validate data and assumptions at system boundaries.
-- Make failure visible and diagnosable without exposing sensitive data.
-- Optimize for future humans and AI agents reading the code.
+- Validate data at system boundaries.
+- Make failures visible and diagnosable without exposing sensitive data.
 - Follow existing repository conventions unless an approved decision changes them.
+- Optimize for code that future humans and AI agents can understand quickly.
 
-## Context-Efficient Changes
+## Scope
 
-- Work on one coherent delivery chunk at a time.
-- Inspect only the files and dependencies needed for that chunk.
-- Avoid mixing unrelated refactors, formatting churn, and features.
-- Keep the project stable and verifiable after each chunk.
-- Split work when too many systems or concerns must be held in context simultaneously.
+- Work on one coherent change at a time.
+- Read only the files and dependencies needed for that work.
+- Avoid unrelated refactors, formatting churn, or speculative cleanup.
+- Keep the repository stable and verifiable after each meaningful change.
+- Split work when too many concerns must be understood at once.
 
-## Types and Contracts
+## Contracts
 
-- Use the strongest practical contract mechanism available in the chosen stack.
-- Avoid untyped or unchecked escape hatches unless justified.
-- Define and validate contracts for external data, configuration, user input, and integration boundaries.
+- Use the strongest practical contract mechanism available in the stack.
+- Avoid unchecked escape hatches unless justified.
+- Validate external data, configuration, user input, and integration boundaries.
+- Keep public contracts explicit and compatibility-conscious.
 
-## User Interface Standards — When Applicable
+## User Interfaces — When Applicable
 
-- Start from the smallest supported viewport when the product supports small screens.
-- Use semantic platform elements before accessibility workarounds.
-- Support keyboard, focus, labels, contrast, reduced motion, and assistive technology according to project targets.
+- Support the project's required screen sizes and input methods.
+- Prefer semantic platform elements.
+- Handle accessibility requirements such as keyboard use, focus, labels,
+  contrast, reduced motion, and assistive technology.
 - Handle relevant loading, empty, error, success, disabled, and permission states.
-- Use shared tokens and primitives when they improve consistency.
+- Reuse shared primitives when they improve consistency.
 
-## Service, API, CLI, Library, and Infrastructure Standards — When Applicable
+## APIs, Services, CLIs, Libraries, and Infrastructure — When Applicable
 
-- Document public contracts and compatibility expectations.
-- Make operational failures actionable.
-- Provide safe defaults and clear configuration errors.
-- Preserve idempotency where repeated execution is possible.
-- Avoid leaking implementation details through public interfaces.
+- Keep public interfaces clear and documented.
+- Provide safe defaults and actionable errors.
+- Preserve idempotency when operations may be repeated.
+- Avoid leaking internal implementation details through public contracts.
 
 ## Testing
 
-Choose tests by behavior and risk:
+Choose tests based on behavior and risk.
+
+Use:
 
 - unit tests for isolated logic
-- component/module tests for reusable units
-- integration tests for boundaries and important flows
-- end-to-end or system tests for critical journeys
-- contract tests when independent systems depend on shared behavior
-
-Avoid tests that only reproduce implementation detail.
-
-## Verification Evidence
-
-These apply to any claim that something works — a test, a manual check, or a
-verification step in a feature's acceptance criteria.
-
-- **Exercise the artifact a user receives, the way a user exercises it.** A
-  hand-written sample of generated output, a local imitation of an external
-  system, or the working tree in place of the built and published thing is
-  evidence about the stand-in, not about the artifact. Prefer one check against
-  the real artifact over several against convenient substitutes.
-- **When a mechanism can fail by doing nothing, observe that the right thing
-  happened.** A clean exit says the command ran. It does not say the effect
-  occurred, and a step that silently does nothing usually reports success.
-- **Beware a check whose every input it supplied itself.** If the test chose the
-  fixtures, the environment, and the trigger, it has confirmed its own
-  assumptions. Name which inputs came from the real system.
-- State what was verified and what was only reasoned about. An unobserved
-  criterion is recorded as unobserved, not as passed.
+- integration tests for important boundaries
+- end-to-end or system tests for critical user flows
+- contract tests when independent systems share a contract
+
+Avoid tests that only reproduce implementation details.
+
+## Verification
+
+Verify the behavior that matters, not just that a command exited successfully.
+
+- Prefer evidence from the real artifact or behavior being claimed.
+- When something can silently do nothing, verify that the intended effect occurred.
+- Beware a check whose every input it supplied itself. Name which inputs came
+  from the real system.
+- Distinguish what was observed from what was only reasoned about.
+- Record unverified behavior as unverified, not passed.
+- Increase verification effort when the cost of being wrong is higher.
 
 ## Dependencies
 
-Before adding one, assess necessity, maintenance, security, runtime cost, licensing, portability, and simpler alternatives. Follow the approval policy in `context/ai-interaction.md`.
+Before adding a dependency, consider whether it is necessary and whether a
+simpler existing option is sufficient.
+
+Follow the approval rules in `context/ai-interaction.md`.
 
 ## Prototype Code
 
-- Treat prototype code as disposable by default.
-- Do not copy it into production merely because it appears to work.
-- Adopt it only through an explicit feature that adds production architecture, validation, tests, accessibility, security, and maintainability as applicable.
+Prototype code is disposable by default.
+
+Do not treat it as production-ready merely because it works.
+
+Adopt prototype work only through an approved production change with the
+necessary validation, tests, security, accessibility, and maintainability.
 
 ## Documentation
 
-- Durable product and architecture truth belongs in `context/project-overview.md`.
-- Active scope belongs in `context/current-feature.md`.
-- Completed outcomes belong in `context/history.md`.
-- Feature-specific contracts belong in `context/features/`.
-- Learning artifacts explain the code but do not replace source-of-truth documentation.
+Keep durable truth in its appropriate project artifact.
+
+- project-wide product and architecture context:
+  `context/project-overview.md`
+- Feature contracts:
+  `context/features/`
+- completed outcomes:
+  `context/history.md`
+- active workspace state:
+  `context/current-feature.md`
+- state handed to the next session:
+  `context/handoff.md`
+
+None of these ships with the kit. Each is written by the workflow that first
+needs it, so a missing one is normal and is not an error.
+
+Learning material explains the implementation but does not replace source-of-truth documentation.
+
+## Version control for `context/`
+
+`context/` holds two kinds of file, and they belong on opposite sides of
+`.gitignore`.
+
+**Track durable project truth.** It is the answer to "what is true about this
+project", it outlives any session, and a reviewer should see it change:
+
+```text
+context/project-overview.md
+context/features/
+context/history.md
+context/tracker.md
+```
+
+**Ignore transient workspace state.** It is the answer to "what was I doing",
+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/handoff.md
+```
+
+Two lines in `.gitignore` are the whole mechanism:
+
+```text
+context/current-feature.md
+context/handoff.md
+```
+
+**Do not ignore `context/` as a directory.** It is the one mistake worth naming,
+because it looks tidier and quietly untracks the project truth every later
+session depends on — including the file that documents your stack and workflow.
+Ignore the two transient files by name.
+
+A team that would rather share workspace state — a single-machine project, or a
+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.

package/copy-list.json

@@ -4,6 +4,7 @@
     "AGENTS.md",
     "CLAUDE.md",
     "context",
+    "roles",
     "skills",
     "templates"
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",
@@ -34,6 +34,7 @@
     "AGENTS.md",
     "CLAUDE.md",
     "context",
+    "roles",
     "skills",
     "templates"
   ],

package/roles/developer.md

@@ -0,0 +1,37 @@
+---
+name: developer
+description: Implements approved work without deciding whether its own work is acceptable.
+---
+
+# Developer
+
+## Responsibility
+
+Implement the approved current work and leave the repository stable.
+
+## Context
+
+Read only what the active Feature and implementation require.
+
+Do not load unrelated history, roadmap, Features, or repository areas by default.
+
+## Use
+
+- `load-feature` to load the work.
+- `start-feature` to implement it.
+- Use the project's existing build, test, and verification commands as needed.
+
+## Rules
+
+- Stay inside the approved scope.
+- Follow existing project conventions.
+- Verify the behavior you change.
+- Do not silently make decisions that require human approval.
+- Do not judge your own work as accepted.
+- Stop and ask when required work would materially widen the scope.
+
+## Finish
+
+Report what changed, what was verified, and anything unresolved.
+
+The human decides what happens next, including whether a `tester` session is needed.

package/roles/planner.md

@@ -0,0 +1,38 @@
+---
+name: planner
+description: Turns approved direction into small, implementable Feature specs.
+---
+
+# Planner
+
+## Responsibility
+
+Turn approved direction into clear Feature specs for another session to
+implement.
+
+## Context
+
+Read only the project context and existing work needed to plan accurately.
+
+Inspect implementation code only when necessary to understand the work.
+
+## Use
+
+- `debate-me` when direction still needs pressure-testing.
+- `to-specs` to create Feature specs.
+
+## Rules
+
+- Do not implement the Features you plan.
+- Do not silently resolve human decisions or `TBD` items.
+- Keep Features small and focused.
+- Do not add workflow metadata that does not help implementation.
+- Prefer fewer Features and fewer artifacts.
+- Record dependencies or technical constraints only when they materially
+  affect the work.
+
+## Finish
+
+Produce the Feature specs and clearly identify any unresolved human decisions.
+
+Stop before implementation.

package/roles/tester.md

@@ -0,0 +1,40 @@
+---
+name: tester
+description: Verifies delivered work against its acceptance criteria and reports findings without repairing them.
+---
+
+# Tester
+
+## Responsibility
+
+Verify that the delivered work behaves as the Feature requires.
+
+Report what is actually observed, not what the implementation intended.
+
+## Context
+
+Read only what testing requires: the Feature spec, the relevant diff, and
+relevant tests or running behavior.
+
+Do not rely on the developer's summary as proof.
+
+## Use
+
+- `review-feature` to verify implemented work.
+- Use the project's existing test commands and relevant testing tools.
+
+## Rules
+
+- Test against the acceptance criteria.
+- Verify important behavior directly when practical.
+- Report real findings clearly, and do not invent findings to justify the role.
+- Do not repair what you find in the same role.
+- Passing tests are evidence, not automatic acceptance.
+- The human decides whether the work is accepted.
+
+## Finish
+
+Report pass or findings, what was actually verified, and anything important
+that remains unverified.
+
+Stop before implementation.

package/skills/challenge-me/SKILL.md

@@ -12,11 +12,12 @@ A good challenge changes the context while preserving the underlying concept.
 
 ## Read First
 
-1. `context/learning/learner-profile.md`
-2. The relevant lesson
-3. `context/learning/progress.md`
-4. The feature spec and focused implementation when needed
-5. Current git status if the challenge may involve code
+1. The relevant lesson
+2. `context/learning/progress.md`
+3. The feature spec and focused implementation when needed
+4. Current git status if the challenge may involve code
+
+Skip any of these that does not exist. Pathfinder creates these files only when a workflow first needs them, so their absence is normal and is not an error. Do not create them just to satisfy this list.
 
 ## Challenge Types
 
@@ -77,5 +78,8 @@ After the learner responds:
 - Identify the strongest decision.
 - Identify the most important weakness.
 - Explain a stronger solution.
-- Update `context/learning/progress.md`.
-- Mark `transferable` only when the concept was applied correctly in the changed context.
+- Update `context/learning/progress.md`, using the confidence scale defined in
+  its `## Confidence Scale` section. If the file does not exist, `quiz-me`
+  carries the header to create it with.
+- Mark `transferable` only when the concept was applied correctly in the changed
+  context, and never using the example that introduced it.

package/skills/complete-feature/SKILL.md

@@ -1,17 +1,23 @@
 ---
 name: complete-feature
-description: Close an accepted feature through final verification, records, delivery metadata, and an optional learning handoff.
+description: Complete accepted work through the project's delivery workflow and durable records.
 ---
 
 # Complete Feature
 
-1. Confirm review findings are resolved or explicitly accepted.
-2. Run final project-appropriate verification.
-3. Confirm each acceptance criterion with evidence.
-4. Follow the approved commit, PR, merge, changelog, versioning, release, and deployment policy—requesting approval where required. After the merge, verify the merged mainline and clean up the merged branch as that policy requires.
-5. Append the durable outcome to `context/history.md` while completing the feature, not afterwards. If the feature was merged without this skill running, still write the entry and record that it was written after the fact.
-6. Mark/reset `context/current-feature.md` and identify the next action.
-7. Offer or invoke `learn-feature` when learning is enabled.
-8. Produce a compact completion summary.
+Complete only work the human has accepted.
 
-Do not claim completion when checks failed, evidence is missing, or the feature remains unaccepted.
+1. Confirm the Feature is accepted.
+2. Run the project's required final checks.
+3. Follow the documented Git, merge, version, release, and deployment workflow.
+   Ask for approval where required.
+4. Mark the Feature complete.
+5. Add a compact entry to `context/history.md`.
+   Create it from `templates/history.template.md` if it does not exist.
+6. Clear or update `context/current-feature.md`. Do nothing if it does not exist.
+7. If work tracking is configured, sync the completed state.
+8. Report the completed outcome and any remaining follow-up.
+
+Do not re-review accepted work unless final verification exposes a new problem.
+
+Do not claim completion if required checks or delivery steps failed.

package/skills/handoff/SKILL.md

@@ -1,12 +1,32 @@
 ---
 name: handoff
-description: Preserve compact factual state so another agent or session can continue safely.
+description: Leave the minimum factual state another session needs to continue safely.
 ---
 
 # Handoff
 
-Read current feature, relevant spec, history, Git state, and verification evidence.
+Create or overwrite `context/handoff.md`.
 
-Return current state, changed outcomes, approved decisions, verification, unresolved issues, assumptions, exact next action, and files worth reading.
+Read only what is needed to describe the current state:
+the active Feature, relevant Git state, and verification already performed.
 
-Keep it compact. Do not include private chain-of-thought or an irrelevant transcript dump.
+Do not load history, roadmap, unrelated Features, or broad repository context
+by default.
+
+Write:
+
+# Handoff
+
+- Feature: `[feature or work]`
+- Done: `[what was completed]`
+- Verified: `[what was actually checked]`
+- Open: `[blocker, finding, or none]`
+- Next: `[single next action]`
+- Read next: `[specific file(s), only when useful]`
+
+Keep it factual and short.
+
+Do not repeat requirements, acceptance criteria, project history, or decisions
+already recorded in their canonical location.
+
+Do not include private chain-of-thought or conversation transcripts.

package/skills/kickstart-pathfinder/SKILL.md

@@ -29,7 +29,7 @@ Ask only what materially affects the project:
 7. Quality priorities: security, accessibility, performance, reliability, privacy, localization
 8. Deployment, environments, cost limits, and external services
 9. Git, review, CI/CD, versioning, changelog, and release preferences
-10. Prototype and learning goals
+10. Prototype direction and learning goals
 11. AI tools and actions requiring human approval
 
 When the user is unsure, provide a small recommendation with reasoning and alternatives.
@@ -42,6 +42,11 @@ When the user is unsure, provide a small recommendation with reasoning and alter
 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.
+   `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.
 
 ## Stop Condition