create-pathfinder 1.3.0

package/AGENTS.md

@@ -0,0 +1,7 @@
+# Agent Entry Point
+
+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.
+
+Use the smallest relevant context for the active task. Keep each delivery chunk stable, reviewable, and verifiable.

package/CLAUDE.md

@@ -0,0 +1,71 @@
+# Project Agent Guide
+
+This repository uses an AI-assisted, human-in-the-loop workflow. Project truth lives in `context/`, reusable behaviors live in `skills/`, and manual launchers live in `prompts/`.
+
+## Read only what is needed
+
+For feature work, usually read:
+
+1. `context/current-feature.md`
+2. its referenced 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
+
+Do not load the whole repo by default.
+
+## Project-selected policies
+
+Follow the stack, architecture, commands, Git workflow, review policy, and release process documented in `context/project-overview.md`.
+
+If a policy is `TBD`, do not invent it. Ask the human or clearly mark it unresolved.
+
+## Before implementation
+
+Restate:
+
+1. Goal
+2. Active delivery chunk
+3. Expected files or areas
+4. Required context
+5. Risks
+6. Assumptions
+7. Verification plan
+8. Out-of-scope work
+9. Current Git state
+10. Intended Git action under the documented workflow
+
+## Human approval
+
+Ask before actions identified in `context/ai-interaction.md`, especially dependency additions, destructive commands, sensitive migrations, commits, merges, and releases.
+
+## Scope and quality
+
+- Implement only the active feature and current delivery chunk.
+- Keep the project stable after each chunk.
+- 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.
+
+## Available skills
+
+- `kickstart-pathfinder` — discover and initialize project context
+- `debate-me` — pressure-test and recommend product, stack, workflow, and prototype direction
+- `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
+- `load-feature` — prepare one feature for implementation
+- `start-feature` — implement scoped delivery chunks
+- `review-feature` — review against requirements, regressions, and standards
+- `complete-feature` — verify and close a feature cleanly
+- `learn-feature` — create an interactive lesson for a completed feature
+- `learn-codebase` — create a modular learning portal for the repository
+- `teach-feature` — teach the verified current feature from its spec, diff, tests, and implementation
+- `teach-architecture` — explain how completed features fit into the wider application and system architecture
+- `quiz-me` — assess understanding of a recently taught feature with evidence-based questions
+- `challenge-me` — create a small transfer exercise applying a learned concept in a changed context
+- `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
+- `skillsmith` — teach and create small local skills

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Lamadrid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+![Pathfinder](https://raw.githubusercontent.com/rikilamadrid/pathfinder/main/assets/logo-wordmark.png)
+
+**An AI-assisted, human-in-the-loop workflow for building software — without giving up the decisions.**
+
+This package installs [Pathfinder](https://github.com/rikilamadrid/pathfinder) into a Git repository you already have.
+
+```bash
+npx create-pathfinder
+```
+
+Then give your agent this prompt:
+
+```text
+Use skills/kickstart-pathfinder/SKILL.md. Help me initialize this project.
+Do not install packages or write product code yet.
+```
+
+## What it installs
+
+Pathfinder is a kit of context files and skills — not a framework. There is no runtime, no dependency, and nothing to build. The installer copies six things into your repository and nothing else:
+
+| Path | What it is |
+| --- | --- |
+| `AGENTS.md`, `CLAUDE.md` | Entry files that tell an agent how to work in the project |
+| `context/` | Project truth — overview, standards, interaction rules, current feature |
+| `skills/` | Nineteen skills covering discovery, specs, delivery, review, and learning |
+| `prompts/` | Manual launchers for tools that do not discover local skills |
+| `templates/` | Starting points the project copies when it needs them |
+
+It never copies Pathfinder's own `README.md`, `CHANGELOG.md`, CI configuration, or brand assets. Your repository gets the workflow, not the project that maintains it.
+
+## What it will not do to your repository
+
+This runs once, in real code, so it is deliberately timid:
+
+- **It never overwrites.** Files that already exist are left exactly as they are and listed by name in the summary. Pass `--force` if you actually want them replaced.
+- **It refuses to run outside a Git repository**, so whatever it writes is reviewable and undoable.
+- **`--dry-run` reports the same plan the real install would carry out**, without writing anything.
+
+Re-running it is safe, and fills in only what is missing.
+
+## Options
+
+| Option | Effect |
+| --- | --- |
+| `--dry-run` | Report what would be written; change nothing |
+| `--force` | Overwrite files that already exist |
+| `-h`, `--help` | Show usage |
+
+## Requirements
+
+Node 18 or newer, and a Git repository. No dependencies — this package installs nothing into your project's `node_modules`, and has none of its own.
+
+## Links
+
+- [Repository and full documentation](https://github.com/rikilamadrid/pathfinder)
+- [Why this is not a framework](https://github.com/rikilamadrid/pathfinder/blob/main/NOT_A_FRAMEWORK.md)
+- [Changelog](https://github.com/rikilamadrid/pathfinder/blob/main/CHANGELOG.md)
+
+MIT © Lamadrid Labs

package/bin/create-pathfinder.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.mjs";
+
+process.exitCode = run(process.argv.slice(2), {
+  cwd: process.cwd(),
+  out: (text) => process.stdout.write(text),
+  err: (text) => process.stderr.write(text),
+});

package/context/ai-interaction.md

@@ -0,0 +1,76 @@
+# AI Interaction Guidelines
+
+This file defines how AI agents collaborate with the human owner. Project-specific choices override generic defaults when explicitly documented.
+
+## Communication
+
+- Be concise, direct, and honest.
+- Distinguish facts, recommendations, assumptions, and unresolved decisions.
+- Do not invent answers for `TBD` items.
+- Stop after 2–3 grounded failed approaches and explain the blocker.
+
+## Approval Boundaries
+
+Follow the project's documented policy. Unless explicitly pre-approved, ask before:
+
+- dependencies or build-tool changes
+- architecture migrations
+- 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
+
+## Git and Delivery
+
+Follow `context/project-overview.md`. Do not assume `main`, feature branches, Git Flow, conventional commits, pull requests, or SemVer.
+
+Before Git actions, inspect current state and state what the documented workflow requires. If the workflow is `TBD`, ask before changing it.
+
+## Feature Lifecycle
+
+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.
+
+## Context Discipline
+
+- 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.
+
+## Prototype Workflow
+
+- 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.
+
+## Scope Control
+
+Do not drift into unrelated refactors, extra features, dependency swaps, broad visual changes, speculative abstractions, or later roadmap items.
+
+## Review Priorities
+
+Use the project's quality priorities. When none are specified, review in this order:
+
+1. correctness
+2. security/privacy
+3. regressions and edge cases
+4. accessibility when applicable
+5. performance
+6. maintainability
+7. consistency
+8. polish
+
+## 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`.

package/context/coding-standards.md

@@ -0,0 +1,72 @@
+# Coding Standards
+
+These standards are stack-agnostic. Extend them after the project selects a real stack; remove sections that do not apply.
+
+## 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.
+- Follow existing repository conventions unless an approved decision changes them.
+
+## Context-Efficient Changes
+
+- 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.
+
+## Types and 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.
+
+## User Interface Standards — 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.
+- Handle relevant loading, empty, error, success, disabled, and permission states.
+- Use shared tokens and primitives when they improve consistency.
+
+## Service, API, CLI, Library, and Infrastructure Standards — 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.
+
+## Testing
+
+Choose tests by behavior and risk:
+
+- 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.
+
+## Dependencies
+
+Before adding one, assess necessity, maintenance, security, runtime cost, licensing, portability, and simpler alternatives. Follow the approval policy 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.
+
+## 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.

package/context/current-feature.md

@@ -0,0 +1,46 @@
+# Current Feature
+
+Use this as the lean tracker for active work.
+
+## Status
+
+- State: `[not started / loaded / in progress / blocked / ready for review / complete]`
+- Feature spec: `[context/features/##-feature-name.md]`
+- Current delivery chunk: `[number and name]`
+- Git state: `[branch/ref and working-tree summary, following project policy]`
+
+## Goal
+
+- `[single feature outcome]`
+
+## Active Delivery Chunk
+
+- `[small stable increment being implemented now]`
+
+## Context Boundary
+
+Read:
+
+- `[required file or folder]`
+
+Avoid loading:
+
+- `[unrelated area]`
+
+## Definition of Done
+
+- `[acceptance result]`
+- `[verification]`
+- `[required docs/state update]`
+
+## Assumptions and Open Questions
+
+- `[assumption or none]`
+
+## Out of Scope
+
+- `[explicit boundary]`
+
+## Up Next
+
+- `[next chunk or feature]`

package/context/features/example-feature-spec.md

@@ -0,0 +1,99 @@
+# [Feature Name]
+
+## Status
+
+Not Started
+
+## Overview
+
+Describe the smallest coherent outcome, where it fits, and why it matters.
+
+## Problem
+
+- What is missing, risky, confusing, inaccessible, unreliable, or inefficient?
+- Who or what is affected?
+- Why does this matter now?
+
+## Goal
+
+State one user-visible or system-verifiable outcome.
+
+## Dependencies
+
+- Earlier feature, system, decision, prototype, or `None`.
+
+## Requirements
+
+- Requirement 1
+- Requirement 2
+- Requirement 3
+- Include relevant failure, permission, loading, empty, retry, responsive, accessibility, operational, or compatibility states only when applicable.
+
+## Out of Scope
+
+- Explicit exclusion
+- Later feature, if known
+- Unrelated refactors, dependencies, or polish
+
+## Experience or Operational Notes — When Applicable
+
+- User interaction, system behavior, responsive behavior, accessibility, observability, performance, security, or operational expectations.
+
+## Technical Notes
+
+Likely areas:
+
+- `[specific path or bounded area]`
+
+Implementation constraints:
+
+- Follow project context and approved prototype direction.
+- Do not silently resolve open architecture decisions.
+- Keep prototype and production code boundaries explicit.
+
+## Context Boundary
+
+Read:
+
+- `[specific context and code]`
+
+Avoid loading:
+
+- `[unrelated systems, old specs, generated output]`
+
+Split this feature further if its required context is not focused enough for reliable implementation and verification.
+
+## Delivery Chunks
+
+1. `[stable, verifiable increment]`
+2. `[stable, verifiable increment]`
+3. `[optional stable increment]`
+
+Each chunk should leave the project stable.
+
+## Acceptance Criteria
+
+- The defined outcome works end to end within scope.
+- Relevant failure and edge behavior is handled.
+- Applicable quality requirements are met.
+- Required automated/manual checks pass.
+- The work can be reviewed independently.
+
+## Verification
+
+- Manual or operational checks:
+- Automated checks:
+- Edge cases:
+- Quality checks:
+
+## Learning Targets
+
+- Concepts worth explaining after completion:
+- Diagram or demonstration opportunity:
+- Quiz ideas:
+
+## Suggested Delivery Metadata
+
+- Git action: `[follow project workflow]`
+- Suggested branch, when applicable: `[project naming convention]`
+- Suggested commit, when applicable: `[project convention]`

package/context/history.md

@@ -0,0 +1,14 @@
+# Project History
+
+Append-only record of completed, accepted work. Prefer durable outcomes over raw file inventories.
+
+## Completed Work
+
+### [YYYY-MM-DD] — [Feature or milestone]
+
+- Outcome:
+- Why it mattered:
+- Verification:
+- Important decision or tradeoff:
+- Learning artifact, if any:
+- Follow-up, if any:

package/context/learning/learner-profile.md

@@ -0,0 +1,35 @@
+# Learner Profile
+
+## Current Level
+
+- Primary role: Senior Frontend Engineer
+- Strongest areas: React, TypeScript, reusable components, design systems, frontend testing
+- Areas to strengthen: system design, complex state, server-state architecture, data visualization, performance at scale, enterprise product architecture, backend integration, real-time systems
+- Target role or environment: Senior frontend/product engineering role building complex enterprise interfaces
+- Preferred learning style: practical explanations grounded in real code, diagrams, comparisons, interview framing, and short challenges
+- Explanation depth: advanced but do not skip fundamentals that affect architectural decisions
+
+## Learning Preferences
+
+- Explain why a solution was selected, not only what the code does.
+- Compare at least one credible alternative when the tradeoff is meaningful.
+- Connect frontend details to system-level consequences.
+- Include accessibility, performance, testing, and maintainability.
+- Use concise Mermaid diagrams when they clarify data or event flow.
+- Prefer varied assessments: prediction, debugging, design choice, code reading, and transfer.
+- Avoid trivia and syntax-only questions unless syntax caused a real issue.
+- Do not overpraise. Give precise feedback.
+
+## Career Preparation
+
+For relevant lessons, include:
+
+- A likely senior frontend interview question
+- A concise strong-answer outline
+- One follow-up question that tests deeper understanding
+- Vocabulary worth using accurately
+- Any gap between the current implementation and production-scale expectations
+
+## Update Rules
+
+Update this file only when the user explicitly changes learning goals or when a repeated pattern is clearly established across multiple lessons.

package/context/learning/progress.md

@@ -0,0 +1,28 @@
+# Learning Progress
+
+This file records demonstrated understanding, not feature completion.
+
+## Confidence Scale
+
+- `introduced` — explained once; no evidence of recall yet
+- `practiced` — answered or applied with help
+- `independent` — applied correctly without meaningful help
+- `transferable` — applied the concept correctly in a different context
+- `review-needed` — misunderstanding or weak recall was observed
+
+## Concept Records
+
+| Concept | Status | Evidence | Last reviewed | Next reinforcement |
+| --- | --- | --- | --- | --- |
+
+## Lessons Completed
+
+| Date | Feature | Lesson | Quiz result | Challenge result | Follow-up |
+| --- | --- | --- | --- | --- | --- |
+
+## Rules
+
+- Do not mark a concept `independent` from passive reading.
+- Do not mark a concept `transferable` using the same example that introduced it.
+- Record uncertainty honestly.
+- Prefer a few meaningful concepts over dozens of shallow entries.