create-pathfinder 1.3.0

package/skills/reverse-engineer/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: reverse-engineer
+description: Analyze an external product, interface, repository, workflow, or reference implementation and produce an evidence-based reconstruction blueprint without copying protected assets or inventing unsupported details.
+---
+
+# Reverse Engineer
+
+Use this skill when the user wants to understand how an existing external product, interface, repository, interaction, animation, or workflow was likely built so they can learn from it, recreate its underlying behavior, or adapt its patterns to their own project.
+
+This skill analyzes references.
+
+It does not initialize a Pathfinder project, implement a feature, or replace `kickstart-pathfinder`, `prototype`, `to-specs`, `learn-codebase`, or the feature delivery loop.
+
+## Appropriate Inputs
+
+The user may provide one or more of:
+
+* a public website or product URL
+* a public repository URL
+* screenshots or screen recordings
+* a live interface
+* product documentation
+* source files the user is authorized to inspect
+* a description of a product or interaction
+* a specific flow, component, animation, or system to analyze
+
+## First Determine the Target
+
+Identify what the user actually wants reverse-engineered:
+
+* visual design
+* user experience
+* interaction behavior
+* animation or motion
+* frontend architecture
+* backend or data flow
+* component structure
+* state management
+* API behavior
+* information architecture
+* business workflow
+* full product system
+
+Do not automatically analyze every layer.
+
+Prefer the narrowest scope that answers the request.
+
+If the target is broad, state which layers can be observed directly and which can only be inferred.
+
+## Evidence Levels
+
+Classify meaningful findings as one of:
+
+* **Observed** — directly visible in the provided reference, source code, network behavior, documentation, or repository.
+* **Strong inference** — not directly visible, but strongly supported by multiple observations.
+* **Possible implementation** — one reasonable way to reproduce the behavior, but not evidence of how the original was built.
+* **Unknown** — cannot be determined from the available evidence.
+
+Never present an inference as a confirmed implementation detail.
+
+## Process
+
+### 1. Define the objective
+
+Restate:
+
+* what is being analyzed
+* what the user wants to learn or reproduce
+* the analysis boundary
+* what evidence is available
+* what cannot be verified
+
+Ask a question only when a missing answer would materially change the analysis.
+
+Otherwise, proceed using clearly stated assumptions.
+
+### 2. Gather evidence
+
+Inspect only the evidence relevant to the requested scope.
+
+Depending on the input, this may include:
+
+* visible page structure
+* responsive behavior
+* navigation and user flows
+* interaction states
+* timing and motion characteristics
+* accessibility semantics
+* repository structure
+* package and configuration files
+* source code boundaries
+* API calls visible through authorized inspection
+* public technical documentation
+* repeated visual or behavioral patterns
+
+Do not perform destructive actions.
+
+Do not attempt to bypass authentication, authorization, paywalls, rate limits, anti-bot controls, or private systems.
+
+### 3. Decompose the system
+
+Break the target into understandable parts such as:
+
+* experience and user flow
+* page or screen hierarchy
+* component hierarchy
+* data and state flow
+* services and integrations
+* animation system
+* responsive behavior
+* accessibility behavior
+* likely architectural boundaries
+
+Use only the sections relevant to the request.
+
+Do not force a full-stack analysis onto a visual interaction request.
+
+### 4. Separate facts from reconstruction choices
+
+For each major area, distinguish:
+
+1. what was observed
+2. what was inferred
+3. what remains unknown
+4. what implementation Pathfinder could use to reproduce the outcome
+
+The reconstruction recommendation does not need to use the original product’s exact stack.
+
+Prefer a solution appropriate for the user’s project, constraints, and existing conventions.
+
+### 5. Identify the transferable pattern
+
+Explain the underlying idea rather than merely listing surface details.
+
+Examples:
+
+* progressive disclosure
+* optimistic interaction
+* scroll-linked storytelling
+* command palette architecture
+* reusable card composition
+* local-first state
+* staged data loading
+* motion used as spatial continuity
+* server-driven configuration
+
+State why the pattern works and where it may fail.
+
+### 6. Produce a reconstruction blueprint
+
+When implementation guidance is requested, include:
+
+* smallest reproducible version
+* logical components or modules
+* state and data responsibilities
+* interaction states
+* responsive requirements
+* accessibility requirements
+* dependencies only when justified
+* risks and unknowns
+* verification approach
+* optional higher-fidelity improvements
+
+Keep the blueprint stack-agnostic unless the user’s project context establishes a stack.
+
+### 7. Recommend the Pathfinder handoff
+
+End by recommending the correct next Pathfinder step.
+
+Use one of these:
+
+* `kickstart-pathfinder` — when this analysis is becoming a new project
+* `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
+* `load-feature` — when the analysis applies to one already-planned feature
+* `learn-codebase` — when the user wants to understand their own repository instead
+* no handoff — when the user only requested analysis
+
+Do not silently run or imitate the responsibilities of those skills.
+
+## Default Output
+
+Use only the sections that add value:
+
+# Reverse-Engineering Report
+
+## Objective
+
+What was analyzed and what the user wants to reproduce or understand.
+
+## Evidence Available
+
+The sources inspected and important limitations.
+
+## Observed Behavior
+
+Directly verifiable findings.
+
+## Likely Structure
+
+Strongly supported architectural, component, data, or interaction inferences.
+
+## Unknowns
+
+Details that cannot be determined honestly.
+
+## Transferable Patterns
+
+The underlying techniques worth learning or adapting.
+
+## Reconstruction Blueprint
+
+A practical implementation approach for the user’s project.
+
+## Risks and Tradeoffs
+
+Complexity, accessibility, performance, maintenance, legal, or fidelity concerns.
+
+## Recommended Pathfinder Handoff
+
+The appropriate next skill, if any, and why.
+
+## Rules
+
+* Distinguish observation from inference.
+* Do not claim to know a private or server-side implementation from surface evidence.
+* Do not copy proprietary source code, trademarks, text, illustrations, icons, audio, video, or other protected assets.
+* Reproduce underlying behavior and patterns, not brand identity.
+* Do not bypass technical or access controls.
+* Do not inspect unrelated parts of a repository or product.
+* Do not modify the user’s project unless explicitly requested through the appropriate Pathfinder delivery skill.
+* Do not install dependencies.
+* Do not create feature files unless the user invokes `to-specs`.
+* Do not create prototype code unless the user invokes `prototype`.
+* Do not turn uncertain technology guesses into requirements.
+* Prefer simple reconstruction approaches over stack imitation.
+* Respect `CLAUDE.md`, `AGENTS.md`, and `context/ai-interaction.md` when operating inside a Pathfinder-enabled repository.
+* Keep the output proportional to the target. A single component should not receive a full product architecture report.
+
+## Quality Check
+
+Before finishing, verify:
+
+* Is the requested target clearly defined?
+* Are observations and inferences visibly separated?
+* Is every major claim supported by available evidence?
+* Are unknowns stated honestly?
+* Does the blueprint reproduce the outcome rather than imitate the brand?
+* Is the recommended implementation appropriate for the user’s project?
+* Does the skill avoid overlapping with another Pathfinder skill?
+* Is the next Pathfinder handoff explicit and correct?

package/skills/review-feature/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: review-feature
+description: Review an implemented feature against its spec, repository standards, regressions, and project quality priorities.
+---
+
+# Review Feature
+
+Review the actual diff and behavior, not only a summary.
+
+## Check
+
+- acceptance criteria and missed requirements
+- regressions, logic errors, edge/failure states
+- security/privacy and data boundaries
+- accessibility, performance, compatibility, and operations when applicable
+- tests and verification quality
+- scope creep and unrelated churn
+- consistency with approved architecture and prototype direction
+- documentation accuracy
+
+## Output
+
+List findings by severity with file/location, impact, and practical fix. Then list verification performed, residual risk, and whether it is ready to complete.
+
+Do not modify code unless the user asks for fixes. Do not manufacture findings to fill a template.

package/skills/skillsmith/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: skillsmith
+description: Teach and help create small, verifiable local agent skills from repeated workflow pain.
+---
+
+# Skillsmith
+
+A skill is a reusable behavior contract, not a project manifesto.
+
+Ask: what repeated task fails, when should the skill trigger, what minimum inputs are needed, what concrete output should result, how is success verified, and what must it not do?
+
+A good skill has a narrow trigger, bounded context, ordered process, human checkpoints where needed, concrete output, stop condition, and conflict-free guardrails.
+
+Teach through one relevant example and one anti-example. Keep version one small and easy to delete.

package/skills/start-feature/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: start-feature
+description: Implement the active feature one stable delivery chunk at a time under the project's approved workflow.
+---
+
+# Start Feature
+
+## Before Coding
+
+Restate goal, chunk, files/areas, context, risks, assumptions, verification, exclusions, Git state, and intended Git action.
+
+## Process
+
+1. Follow the project's documented Git and approval policy.
+2. Read only the active chunk's context.
+3. Implement the smallest complete change.
+4. Verify the chunk with relevant checks.
+5. Keep the project stable.
+6. Update current-feature state and move to the next chunk only when appropriate.
+
+## Rules
+
+- Stop on conflicts between spec, durable context, and repository reality.
+- Do not add dependencies, expand scope, adopt prototype code, commit, merge, or deploy without the documented approval.
+- Do not hide multiple features inside one delivery chunk.

package/skills/teach-architecture/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: teach-architecture
+description: Explain how one or more completed features fit into the wider application and system architecture.
+argument-hint: optional scope such as frontend, data, realtime, testing, or full
+---
+
+# Teach Architecture
+
+Use this skill when the learner understands an individual feature and needs to zoom out.
+
+The goal is to connect implementation details to system boundaries, ownership, scaling, and team architecture.
+
+## Read First
+
+1. `context/project-overview.md`
+2. `context/learning/learner-profile.md`
+3. Relevant completed feature specs and lessons
+4. Architecture-relevant source files only
+5. Data contracts, API boundaries, stores, routing, and deployment configuration relevant to the requested scope
+6. Existing ADRs, if present
+
+Do not infer services or infrastructure that do not exist. Clearly distinguish current architecture from likely future architecture.
+
+## Teach These Layers
+
+Select only the relevant layers:
+
+- Product surfaces and user journeys
+- Component and design-system boundaries
+- Feature/module boundaries
+- Client state versus server state
+- Data fetching and cache lifecycle
+- API and backend contracts
+- Persistence
+- Authentication and authorization
+- Event and real-time flows
+- Observability and failure handling
+- Testing pyramid and contract boundaries
+- Build, deployment, and runtime boundaries
+- Team ownership and package boundaries
+- Performance and scale limits
+
+## Required Output
+
+Create or update a scoped lesson under:
+
+```text
+context/learning/lessons/YYYY-MM-DD-architecture-[scope].md
+```
+
+Include:
+
+1. Current architecture
+2. A Mermaid container or flow diagram
+3. Dependency direction
+4. State and data ownership
+5. Important invariants
+6. Failure paths
+7. Scaling pressure points
+8. Credible alternative architecture
+9. Why the current level of complexity is or is not appropriate
+10. Senior interview questions and answer outlines
+
+## Architecture Honesty
+
+Use labels such as:
+
+- `implemented`
+- `mocked`
+- `planned`
+- `recommended later`
+
+Do not present a future target diagram as current reality.
+
+## Scope
+
+- Do not refactor code.
+- Do not introduce microservices, microfrontends, queues, or real-time infrastructure merely to make the diagram impressive.
+- Prefer the simplest architecture that satisfies current requirements.

package/skills/teach-feature/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: teach-feature
+description: Teach the verified current feature from its spec, diff, tests, and implementation without changing product code.
+---
+
+# Teach Feature
+
+Use this skill after a feature has been implemented and reviewed, or when the user explicitly asks to understand an existing feature.
+
+The goal is not to produce generic documentation. The goal is to help the learner build a durable mental model from the actual repository.
+
+## Read First
+
+Read only the smallest useful context:
+
+1. `context/learning/learner-profile.md`
+2. `context/current-feature.md`
+3. The source feature spec under `context/features/`
+4. `context/project-overview.md`
+5. The current branch, working tree status, and focused diff
+6. Tests and implementation files touched by the feature
+7. Relevant ADR, coding standard, or design-system guidance only when it materially affects the feature
+
+Do not read the entire repository by default.
+
+If the feature or diff cannot be identified, ask for the branch, spec, commit range, or explicit file set.
+
+## Reconcile Before Teaching
+
+Briefly determine:
+
+- What the spec intended
+- What the implementation actually does
+- What tests verify
+- Any drift, incomplete work, or uncertainty
+
+Do not teach planned behavior as if it exists.
+
+## Teaching Goals
+
+Explain:
+
+- The user or system problem
+- The feature boundary
+- The mental model
+- Event and data flow
+- Responsibilities of important files
+- State ownership and synchronization
+- Error, loading, empty, and success behavior
+- Testing strategy
+- Accessibility implications
+- Performance implications
+- Maintainability and extension points
+- Meaningful decisions and tradeoffs
+- Production-scale gaps
+- Senior-level interview framing
+
+## Adaptation
+
+Use `context/learning/learner-profile.md`.
+
+For an experienced engineer:
+
+- Do not spend most of the lesson paraphrasing syntax.
+- Explain architectural consequences.
+- Compare credible alternatives.
+- Identify hidden coupling and invariants.
+- Connect component-level decisions to team and system scale.
+- Point out gaps directly and constructively.
+
+## Lesson Artifact
+
+Create:
+
+```text
+context/learning/lessons/YYYY-MM-DD-[feature-slug].md
+```
+
+Use `templates/lesson.template.md`.
+
+Keep the lesson focused. Prefer five strong transferable concepts over twenty shallow observations.
+
+Mermaid diagrams are encouraged for:
+
+- event flow
+- state ownership
+- request lifecycle
+- component boundaries
+- dependency direction
+
+## Interaction Rule
+
+After producing the lesson, stop and offer exactly one recommended next action:
+
+- `quiz-me`
+- `challenge-me`
+- `teach-architecture`
+- a later spaced review
+- no follow-up needed
+
+Do not automatically run the next skill.
+
+## Safety and Scope
+
+- Do not modify product code.
+- Do not install packages.
+- Do not commit or merge.
+- Do not invent intent that is unsupported by code or specs.
+- Do not reveal private chain-of-thought.
+- Explain evidence, reasoning summaries, and tradeoffs.

package/skills/to-specs/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: to-specs
+description: Convert approved project context into small sequential feature specs optimized for focused LLM context and reliable delivery.
+---
+
+# To Specs
+
+## Readiness Check
+
+Confirm:
+
+- MVP and first useful flow are defined
+- critical stack and workflow choices are approved or deliberately deferred
+- required prototype direction is approved
+- known verification methods exist or are explicitly deferred
+- no material context contradictions remain
+
+If not ready, report the blockers instead of inventing decisions.
+
+## Sizing Principles
+
+Each feature should:
+
+- create one visible or system-verifiable outcome
+- fit one focused branch/change set under the project's workflow
+- be independently reviewable and verifiable
+- require a coherent, bounded set of context
+- state dependencies, assumptions, and exclusions
+- contain stable delivery chunks
+
+Split a feature when it mixes several systems, requires a repo-wide mental model, combines infrastructure with unrelated UX/polish, or cannot be verified independently.
+
+## Output
+
+Create only the coherent MVP roadmap in `context/features/`, using the example template and project-selected naming/delivery policies.
+
+Each spec must include Context Boundary, Delivery Chunks, and Learning Targets.
+
+After creation, summarize file, outcome, dependency, visible/verifiable win, context risk, and recommended first feature.
+
+## Rules
+
+- Do not implement or install packages.
+- Do not assume UI, mobile, a framework, a branch type, or conventional commits.
+- Do not plan the entire dream product.