create-pathfinder 1.3.0

package/context/project-overview.md

@@ -0,0 +1,198 @@
+# [Project Name] — Project Overview
+
+> Describe the product, audience, intended feeling, and reason it should exist.
+
+## Status
+
+- Stage: `[idea / prototype / MVP / production / maintenance]`
+- Repo type: `[new / existing / application / library / service / monorepo / other]`
+- Primary goal: `[success definition]`
+- Prototype status: `[not required / recommended / in progress / approved / rejected / TBD]`
+
+## Decision States
+
+- `TBD` — human decision required
+- `None` — intentionally excluded
+- `N/A` — not applicable
+- `Deferred` — intentionally postponed
+
+## Product Vision
+
+- Problem:
+- Primary user:
+- First useful outcome:
+- Distinctive quality:
+- What this must avoid becoming:
+
+## MVP Boundary
+
+### In scope
+
+- `[essential outcome]`
+
+### Out of scope
+
+- `[deferred outcome]`
+
+### Success signals
+
+- `[observable user, business, system, or learning signal]`
+
+## Core Experience or System Flow
+
+```text
+starting state -> action/process -> useful result -> reason to return or continue
+```
+
+## Requirements, Preferences, Constraints, and Open Decisions
+
+| Type | Item | Notes |
+| --- | --- | --- |
+| Requirement | `[must be true]` | |
+| Preference | `[desired but negotiable]` | |
+| Constraint | `[limit or external obligation]` | |
+| Open decision | `[TBD]` | |
+
+## Recommended and Approved Technology
+
+Recommendations may be proposed by `debate-me`; approved choices belong here.
+
+| Layer | Approved choice | Reason | Status |
+| --- | --- | --- | --- |
+| Platform/runtime | `TBD` | | |
+| Language(s) | `TBD` | | |
+| UI/presentation | `TBD / N/A` | | |
+| Backend/application layer | `TBD / None` | | |
+| Data storage | `TBD / None` | | |
+| Data access/ORM | `TBD / None` | | |
+| Authentication | `TBD / None` | | |
+| Authorization | `TBD / None` | | |
+| API/integration style | `TBD / None` | | |
+| State management | `TBD / N/A` | | |
+| Testing | `TBD` | | |
+| Build/package tooling | `TBD` | | |
+| Deployment/runtime environment | `TBD` | | |
+| Observability | `TBD / Deferred` | | |
+| AI providers/models | `TBD / None` | | |
+
+## Architecture
+
+- Architecture style: `TBD`
+- Repository shape: `TBD`
+- Main boundaries/modules:
+- Data/control flow:
+- Important tradeoffs:
+
+```text
+[path or module]    # purpose
+[path or module]    # purpose
+```
+
+## Prototype Direction
+
+- Prototype needed: `[yes / no / TBD]`
+- Type: `[experience / technical / diagram / mixed / N/A]`
+- Assumption being validated:
+- Output location:
+- Review criteria:
+- Approved direction:
+- Elements explicitly not adopted into production:
+
+## Delivery Workflow
+
+| Area | Choice |
+| --- | --- |
+| Git workflow | `TBD` |
+| Default/stable branch | `TBD` |
+| Branch naming | `TBD / N/A` |
+| Commit convention | `TBD / None` |
+| Pull request policy | `TBD` |
+| Merge strategy | `TBD` |
+| CI/CD | `TBD / None` |
+| Versioning | `TBD / None` |
+| Changelog | `TBD / None` |
+| Release process | `TBD / None` |
+
+## Environments and Integrations
+
+| Area | Choice | Notes |
+| --- | --- | --- |
+| Local development | `TBD` | |
+| Preview/staging | `TBD / None` | |
+| Production | `TBD / None` | |
+| Environment configuration | `TBD` | |
+| Secrets management | `TBD / N/A` | |
+| External APIs/services | `TBD / None` | |
+| Rate/cost limits | `TBD / N/A` | |
+
+## Quality Priorities
+
+Rank only what matters for this project.
+
+1. `[priority]`
+2. `[priority]`
+3. `[priority]`
+
+| Concern | Target or decision |
+| --- | --- |
+| Correctness/reliability | `TBD` |
+| Security/privacy | `TBD / N/A` |
+| Accessibility | `TBD / N/A` |
+| Performance | `TBD / N/A` |
+| Browser/platform support | `TBD / N/A` |
+| Localization | `TBD / None` |
+| Offline behavior | `TBD / N/A` |
+
+## Core Domain Concepts
+
+Describe durable concepts without assuming a language:
+
+```text
+Entity/Concept: Example
+Required fields: id, name
+Important states: draft, active, archived
+Relationships: belongs to / contains / references
+```
+
+## Build, Test, and Run Commands
+
+```text
+install: TBD
+run/dev: TBD
+test: TBD
+lint/static analysis: TBD
+build/package: TBD
+other verification: TBD
+```
+
+## Build Phases
+
+| Phase | Goal | Visible or verifiable win |
+| --- | --- | --- |
+| 1 | Foundation | `[result]` |
+| 2 | Core experience/system | `[result]` |
+| 3 | Real data/integration | `[result]` |
+| 4 | Quality and release readiness | `[result]` |
+
+## Learning Goals
+
+- What the human wants to understand:
+- Preferred lesson format: `[HTML / MDX / Markdown / existing docs system / TBD]`
+- Quiz preferences:
+- Topics to emphasize:
+- Topics to avoid over-explaining:
+
+## Durable Decisions
+
+| Date | Decision | Reason | Status |
+| --- | --- | --- | --- |
+| `[YYYY-MM-DD]` | `[decision]` | `[reason]` | `[proposed / accepted / superseded]` |
+
+## Things To Avoid
+
+- Building before critical decisions are understood.
+- Treating recommendations as approval.
+- Silently resolving `TBD` items.
+- Turning prototype shortcuts into production defaults.
+- Over-documenting temporary implementation detail.
+- Creating feature specs too large for a focused LLM context window.

package/copy-list.json

@@ -0,0 +1,11 @@
+{
+  "description": "The canonical list of what a destination project receives when the Pathfinder kit is installed. This file is the single source of truth. src/kit.mjs reads it at runtime, .github/scripts/validate-kit.py checks every other statement of the list against it, and npm publishes it inside the package so the installer is self-contained. Change the list here and nowhere else; validation will name whatever falls out of step.",
+  "entries": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "context",
+    "prompts",
+    "skills",
+    "templates"
+  ]
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "create-pathfinder",
+  "version": "1.3.0",
+  "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
+  "keywords": [
+    "pathfinder",
+    "ai",
+    "agent",
+    "claude",
+    "workflow",
+    "skills",
+    "scaffold"
+  ],
+  "license": "MIT",
+  "author": "Ricardo Lamadrid (Lamadrid Labs)",
+  "homepage": "https://github.com/rikilamadrid/pathfinder#readme",
+  "bugs": "https://github.com/rikilamadrid/pathfinder/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rikilamadrid/pathfinder.git",
+    "directory": "packages/create-pathfinder"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "create-pathfinder": "bin/create-pathfinder.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "copy-list.json",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "context",
+    "prompts",
+    "skills",
+    "templates"
+  ],
+  "scripts": {
+    "stage": "node scripts/stage-kit.mjs",
+    "unstage": "node scripts/stage-kit.mjs --clean",
+    "prepack": "node scripts/stage-kit.mjs",
+    "postpack": "node scripts/stage-kit.mjs --clean",
+    "prepublishOnly": "node scripts/publish-guard.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prompts/01-kickstart-project.md

@@ -0,0 +1 @@
+Use `skills/kickstart-pathfinder/SKILL.md` to discover and initialize this new or existing project. Ask progressively, preserve existing repo facts, distinguish recommendations from approved choices, and do not install packages, generate feature specs, or write product code yet.

package/prompts/01-teach-current-feature.md

@@ -0,0 +1,9 @@
+Use `skills/teach-feature/SKILL.md`.
+
+Teach me the verified current feature from its spec, focused diff, implementation, and tests.
+
+Adapt the depth to `context/learning/learner-profile.md`.
+
+Create the lesson under `context/learning/lessons/`.
+
+Do not modify product code, install packages, commit, or merge.

package/prompts/02-debate-me.md

@@ -0,0 +1 @@
+Use `skills/debate-me/SKILL.md` to pressure-test this idea or project. Recommend an MVP, technology/architecture, delivery workflow, and prototype checkpoint based on the findings. Present them for my acceptance, modification, comparison, or deferral; do not silently approve them for me.

package/prompts/02-quiz-current-feature.md

@@ -0,0 +1,7 @@
+Use `skills/quiz-me/SKILL.md`.
+
+Quiz me on the most recent lesson for the current feature.
+
+Ask one question at a time. Use varied question formats. Diagnose understanding rather than rewarding memorization.
+
+Update `context/learning/progress.md` conservatively after the quiz.

package/prompts/03-challenge-current-feature.md

@@ -0,0 +1,7 @@
+Use `skills/challenge-me/SKILL.md`.
+
+Create a small transfer challenge based on the current feature's lesson and my learning gaps.
+
+Change at least one meaningful constraint so I must apply the concept in a new context.
+
+Do not modify code until I explicitly approve implementation.

package/prompts/03-prototype.md

@@ -0,0 +1 @@
+Use `skills/prototype/SKILL.md` to validate the most important unresolved assumption with the cheapest useful prototype. Define review criteria, create or iterate the artifact, and do not treat it as production code.

package/prompts/04-teach-current-architecture.md

@@ -0,0 +1,7 @@
+Use `skills/teach-architecture/SKILL.md`.
+
+Explain how the current feature fits into the wider application architecture.
+
+Clearly distinguish implemented, mocked, planned, and later-recommended architecture.
+
+Create a concise architecture lesson with Mermaid diagrams. Do not refactor code.

package/prompts/04-to-specs.md

@@ -0,0 +1 @@
+Use `skills/to-specs/SKILL.md` to create a coherent MVP roadmap of context-sized, independently verifiable feature specs. Do not implement code or invent unresolved decisions.

package/prompts/05-learning-review.md

@@ -0,0 +1,5 @@
+Use `skills/learning-review/SKILL.md` in interview mode.
+
+Review my recent lessons, quizzes, challenges, completed features, and progress.
+
+Identify what I can credibly explain in a senior frontend interview, where my evidence is weak, and the three highest-value concepts to reinforce through upcoming features.

package/prompts/05-load-feature.md

@@ -0,0 +1 @@
+Use `skills/load-feature/SKILL.md` to prepare the requested or next feature, validate its dependencies and context size, and populate `context/current-feature.md`. Do not implement yet.

package/prompts/06-start-feature.md

@@ -0,0 +1 @@
+Use `skills/start-feature/SKILL.md` to implement the active feature one stable delivery chunk at a time under the project-selected workflow.

package/prompts/07-review-feature.md

@@ -0,0 +1 @@
+Use `skills/review-feature/SKILL.md` to review the actual implementation against its spec, regressions, and project quality priorities. Report findings before changing code.

package/prompts/08-complete-feature.md

@@ -0,0 +1 @@
+Use `skills/complete-feature/SKILL.md` to verify, record, and close the accepted feature under the project delivery policy, then route to feature learning when enabled.

package/prompts/09-learn-feature.md

@@ -0,0 +1 @@
+Use `skills/learn-feature/SKILL.md` to create a rich interactive lesson and varied quiz for the completed feature, scoped to its implementation and direct dependencies.

package/prompts/10-learn-codebase.md

@@ -0,0 +1 @@
+Use `skills/learn-codebase/SKILL.md` to create a modular interactive learning portal for this repository at the current milestone.

package/prompts/11-handoff.md

@@ -0,0 +1 @@
+Use `skills/handoff/SKILL.md` to create a compact factual handoff for the next agent or session.

package/prompts/12-skillsmith.md

@@ -0,0 +1 @@
+Use `skills/skillsmith/SKILL.md` to teach me how to design or improve a small local skill for a repeated workflow problem.

package/prompts/13-reverse-engineer.md

@@ -0,0 +1,18 @@
+Use `skills/reverse-engineer/SKILL.md`.
+
+Reverse-engineer the reference I provide.
+
+Focus on the specific product, experience, system, component, animation, repository, or workflow I name.
+
+Clearly separate:
+
+* directly observed behavior
+* strong inferences
+* possible reconstruction choices
+* unknown details
+
+Explain the transferable patterns and produce a practical reconstruction blueprint.
+
+Do not copy protected assets or claim unsupported knowledge about private implementation details.
+
+Do not modify project files, create feature specs, install dependencies, or implement code unless I explicitly invoke the appropriate Pathfinder skill afterward.

package/prompts/14-reflect.md

@@ -0,0 +1,13 @@
+Use `skills/reflect/SKILL.md`.
+
+Reflect on the completed work I name.
+
+Reconstruct what actually happened from repository evidence, then classify each finding as PROJECT, WORKFLOW CANDIDATE, or NOISE.
+
+Only propose a Pathfinder change when the lesson would still hold in another language, framework, and business domain, and is not already covered by an existing skill or document.
+
+Prefer the smallest durable improvement. Concluding that Pathfinder should not change is a valid result.
+
+Then make one bounded pass over the reflection itself. Report `No Reflect improvement proposed.` unless evidence shows the process genuinely failed to do its job. Do not recurse further.
+
+Do not modify Pathfinder, `AGENTS.md`, skills, prompts, or project files as part of reflection. Propose the changes and wait for my decision.

package/skills/challenge-me/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: challenge-me
+description: Create a small transfer exercise that applies a learned feature concept in a changed context.
+argument-hint: design|debug|refactor|implement
+---
+
+# Challenge Me
+
+Use this skill after a lesson or quiz when the user wants to apply the concept rather than merely recall it.
+
+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
+
+## Challenge Types
+
+Choose one, or honor the requested argument:
+
+- `design` — propose an architecture or API under new constraints
+- `debug` — diagnose a realistic defect
+- `refactor` — improve structure while preserving behavior
+- `implement` — build a small extension in a sandboxed or explicit feature branch
+
+## Challenge Requirements
+
+The challenge must include:
+
+- Scenario
+- Learning objective
+- Constraints
+- Definition of done
+- Evidence expected from the learner
+- Hints, hidden initially
+- Evaluation rubric
+
+Keep it small enough for one focused session.
+
+## Transfer Rule
+
+Do not simply ask the learner to reproduce the same feature.
+
+Change at least one meaningful dimension:
+
+- data volume
+- asynchronous behavior
+- user role
+- accessibility requirement
+- failure mode
+- state ownership
+- real-time updates
+- backend contract
+- performance constraint
+- mobile interaction
+- team or package boundary
+
+## Coding Safety
+
+For `implement` or `refactor`:
+
+- Explain the proposed scope first.
+- Do not edit code until the user explicitly approves implementation.
+- Use a feature branch.
+- Do not merge or commit without permission.
+- Keep challenge code separate from production work when appropriate.
+
+## Evaluation
+
+After the learner responds:
+
+- Evaluate against the rubric.
+- 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.

package/skills/complete-feature/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: complete-feature
+description: Close an accepted feature through final verification, records, delivery metadata, and an optional learning handoff.
+---
+
+# 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.
+5. Append the durable outcome to `context/history.md`.
+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.
+
+Do not claim completion when checks failed, evidence is missing, or the feature remains unaccepted.

package/skills/debate-me/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: debate-me
+description: Pressure-test an idea or project and recommend an MVP, technology, delivery workflow, and prototype checkpoint for human selection.
+---
+
+# Debate Me
+
+Use this skill before implementation when important product or technical choices deserve challenge.
+
+## Inputs
+
+Read the user's idea and the smallest relevant project context. Inspect an existing repo only enough to respect its constraints.
+
+## Debate Areas
+
+- user/problem clarity and first useful outcome
+- MVP cuts and differentiation
+- product, UX, operational, data, integration, security, and maintenance risks
+- architecture and technical complexity
+- team, budget, deadline, platform, and learning constraints
+- testing, deployment, and supportability
+- need for an experience or technical prototype
+
+## Output
+
+### Strongest Version of the Idea
+
+A sharper restatement.
+
+### Keep in MVP / Cut from MVP
+
+Protect the first useful version.
+
+### Biggest Risks
+
+3–7 risks with practical mitigation.
+
+### Questions That Materially Change the Build
+
+Only unresolved questions with real consequences.
+
+### Recommended Project Setup
+
+Recommend, when relevant:
+
+- product shape and architecture
+- platform/runtime and language
+- UI/presentation approach
+- backend, database/data access, auth/authorization, APIs
+- testing and observability
+- deployment/environments
+- Git workflow, branching, commits, reviews, CI/CD, versioning, releases
+
+For each choice, explain why it fits and label it `recommended`, not `approved`.
+
+### Prototype Recommendation
+
+State one of:
+
+- no prototype needed
+- experience prototype
+- technical proof of concept
+- architecture/data-flow prototype
+- mixed prototype
+
+Define the assumption to validate, cheapest useful format, review criteria, and what must not be mistaken for production code.
+
+### Human Choice
+
+Ask the user to choose:
+
+1. accept the recommendations
+2. modify selected choices
+3. compare alternatives
+4. leave specific items `TBD`
+5. prototype before deciding
+
+Do not write approved context until the human responds.
+
+### Recommended Next Move
+
+Choose `prototype`, `kickstart-pathfinder`, `to-specs`, or pause.

package/skills/handoff/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: handoff
+description: Preserve compact factual state so another agent or session can continue safely.
+---
+
+# Handoff
+
+Read current feature, relevant spec, history, Git state, and verification evidence.
+
+Return current state, changed outcomes, approved decisions, verification, unresolved issues, assumptions, exact next action, and files worth reading.
+
+Keep it compact. Do not include private chain-of-thought or an irrelevant transcript dump.

package/skills/kickstart-pathfinder/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: kickstart-pathfinder
+description: Discover and initialize a new or existing project without writing product code.
+---
+
+# Kickstart Pathfinder
+
+Use this skill to turn an idea or existing repository into durable, human-approved project context.
+
+## Rules
+
+- Do not install packages or write product code.
+- Inspect existing repositories lightly and preserve established facts.
+- Ask progressively; do not dump a giant questionnaire.
+- Classify answers as requirements, preferences, constraints, or open decisions.
+- Distinguish recommendations from approved choices.
+- Never silently resolve `TBD` decisions.
+
+## Discovery Areas
+
+Ask only what materially affects the project:
+
+1. Product, audience, first useful outcome, success signal
+2. MVP boundary and explicit exclusions
+3. Platform and experience type
+4. Existing technical constraints or preferred technologies
+5. Data, backend, database, auth, APIs, AI, payments, files, offline needs
+6. Architecture and repository shape
+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
+11. AI tools and actions requiring human approval
+
+When the user is unsure, provide a small recommendation with reasoning and alternatives.
+
+## 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.
+7. Recommend `debate-me`, `prototype`, or `to-specs` as the next action.
+
+## Stop Condition
+
+Stop before feature specs, dependency installation, scaffolding, or implementation.

package/skills/learn-codebase/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: learn-codebase
+description: Generate a modular, interactive learning portal that explains an entire codebase at a milestone.
+---
+
+# Learn Codebase
+
+Use for onboarding, milestone review, handoff, or interview preparation—not after every feature.
+
+## Process
+
+1. Establish learning goals and audience.
+2. Map the repository deliberately, excluding generated/vendor/build output.
+3. Identify architecture, modules, domain concepts, major flows, tests, deployment, and durable decisions.
+4. Generate modular lessons rather than one giant document.
+5. Include navigable diagrams, demonstrations, exercises, and quizzes.
+6. Cite source paths and distinguish current behavior from recommendations.
+
+## Default Output
+
+```text
+learning/codebase/
+├── index.html
+├── modules/
+├── assets/
+└── README.md
+```
+
+Use self-contained HTML/CSS/JS by default; use an existing docs/MDX system when approved. Do not install a framework solely for the portal without approval.
+
+## Modules May Include
+
+orientation, architecture, domain/data flow, UI or interfaces, services/integrations, testing, deployment/operations, security boundaries, extension exercises, and cumulative quiz.