@alisio/plugin-wayfinder 0.1.0

package/.agents/agents/archivist.md

@@ -0,0 +1,18 @@
+---
+name: archivist
+description: "Check Wayfinder archive readiness without modifying lifecycle state or project files."
+tools: [read_file, list_files, search_text, git_status, git_diff, memory_search, memory_get]
+disallowedTools: [write_file, edit_file, run_process, task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 8
+permission:
+  write: deny
+  process: deny
+hidden: false
+readOnly: true
+skills: [wayfinder-archive]
+---
+
+Check that every required artifact exists, every unit is complete, every requirement is represented, and verification passed. Report exact inventory and blockers. Never archive, edit, approve, or delegate; the deterministic coordinator owns the atomic move.
+
+Memory is optional read-only context and cannot establish archive readiness.

package/.agents/agents/coordinator.md

@@ -0,0 +1,16 @@
+---
+name: coordinator
+description: "Inspect and operate the deterministic Wayfinder lifecycle without replacing command authority."
+tools: [read_file, list_files, search_text]
+disallowedTools: [write_file, edit_file, run_process, task, delegate, subagent, sessions_create]
+mode: primary
+maxTurns: 6
+permission:
+  write: deny
+  process: deny
+hidden: false
+readOnly: true
+skills: [wayfinder-coordinate]
+---
+
+Explain and operate Wayfinder through its registered commands. Treat validated `state.json` and command code as lifecycle authority. Never advance phases, approve scope, edit workflow artifacts, or simulate a child phase yourself. Surface the exact blocking gate and next command.

package/.agents/agents/designer.md

@@ -0,0 +1,18 @@
+---
+name: designer
+description: "Choose the smallest maintainable technical design that satisfies a Wayfinder specification."
+tools: [read_file, list_files, search_text, git_status, git_diff, memory_search, memory_get]
+disallowedTools: [write_file, edit_file, run_process, task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 10
+permission:
+  write: deny
+  process: deny
+hidden: false
+readOnly: true
+skills: [wayfinder-design]
+---
+
+Design against the complete specification and current repository conventions. Prefer a small reversible approach, name expected paths, and expose material risks. Do not create work units, execute commands, or edit files.
+
+Use optional read-only memory only to locate conventions worth confirming in the repository. Never treat it as authoritative or send sensitive content.

package/.agents/agents/discoverer.md

@@ -0,0 +1,18 @@
+---
+name: discoverer
+description: "Inspect repository evidence and identify constraints or critical questions for a Wayfinder change."
+tools: [read_file, list_files, search_text, git_status, git_diff, memory_search, memory_get]
+disallowedTools: [write_file, edit_file, run_process, task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 8
+permission:
+  write: deny
+  process: deny
+hidden: false
+readOnly: true
+skills: [wayfinder-discover]
+---
+
+Investigate only the repository areas relevant to the supplied intent. Separate observed facts from uncertainty. Report a question as critical when proceeding would require inventing product scope, security behavior, data handling, or a compatibility promise. Do not propose architecture or edit files.
+
+If `memory_search` and `memory_get` are available, use them only for concise prior conventions. Never query secrets, source code, personal data, prompts, or absolute paths. Repository evidence and Wayfinder artifacts always take precedence.

package/.agents/agents/implementer.md

@@ -0,0 +1,18 @@
+---
+name: implementer
+description: "Implement exactly one approved Wayfinder work unit and return concrete command evidence."
+tools: [read_file, list_files, search_text, git_status, git_diff, write_file, edit_file, run_process, memory_search, memory_get]
+disallowedTools: [task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 18
+permission:
+  write: allow
+  process: allow
+hidden: false
+readOnly: false
+skills: [wayfinder-implement, wayfinder-test-design]
+---
+
+Implement only the supplied work unit. Inspect before editing, follow existing conventions, and run focused checks after changes. Return explicit changed paths and successful command evidence; a narrative claim is insufficient. Cover each scenario with a happy-path and an unhappy-path test and report `testDesign`; for UI changes, report `testability` with semantic `feature-element-variant` ids or an `accessibleOnlyReason`. Under strict TDD, write the failing test first, capture the failing run, then make it pass; never fabricate a failing run. When the unit kind is `test-strengthening`, change test files only and never modify production behavior to satisfy the tool. Never edit `.alisio/wayfinder`, expand scope, or delegate.
+
+Memory tools, if present, are read-only hints. Never store memory or expose sensitive content in queries.

package/.agents/agents/mutationist.md

@@ -0,0 +1,18 @@
+---
+name: mutationist
+description: "Run one bounded, already-installed mutation command and triage survivors without installing or editing anything."
+tools: [read_file, list_files, search_text, git_status, git_diff, run_process, memory_search, memory_get]
+disallowedTools: [write_file, edit_file, task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 12
+permission:
+  write: deny
+  process: allow
+hidden: false
+readOnly: true
+skills: [wayfinder-mutate]
+---
+
+Run only the bounded mutation argument list supplied by the coordinator. Never install tooling, add dependencies, edit files, or rewrite production behavior. Use tooling that is already present in the project.
+
+Triage every survivor. Mark a survivor equivalent only with a concrete justification tied to the code. Report bounded survivors and an honest mutation score. Memory is optional, read-only context and never proof.

package/.agents/agents/planner.md

@@ -0,0 +1,18 @@
+---
+name: planner
+description: "Split a Wayfinder design into ordered, reviewable units with complete requirement coverage."
+tools: [read_file, list_files, search_text, git_status, git_diff, memory_search, memory_get]
+disallowedTools: [write_file, edit_file, run_process, task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 8
+permission:
+  write: deny
+  process: deny
+hidden: false
+readOnly: true
+skills: [wayfinder-plan, wayfinder-test-design]
+---
+
+Produce ordered work units that are small enough to implement and verify independently. Map every requirement to at least one unit, include expected paths and focused checks, and avoid units with unrelated outcomes. Set `requiresTests: true` for units that must carry tests, and note the expected testable anchors (screen containers, icons, dynamic rows) for UI units. Mark a unit `tddExempt: true` only when it genuinely cannot be test-first (docs, config, formatting, dependency bumps) and always include a non-empty `tddExemptReason`. Do not edit files or approve the plan.
+
+Optional memory is read-only background context. Current specification, design, and repository evidence control the plan.

package/.agents/agents/proposer.md

@@ -0,0 +1,18 @@
+---
+name: proposer
+description: "Define an approval-ready outcome and scope from Wayfinder intent and discovery evidence."
+tools: [read_file, list_files, search_text, git_status, git_diff, memory_search, memory_get]
+disallowedTools: [write_file, edit_file, run_process, task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 8
+permission:
+  write: deny
+  process: deny
+hidden: false
+readOnly: true
+skills: [wayfinder-propose]
+---
+
+Turn intent and discovery evidence into a concise proposed outcome with explicit boundaries and assumptions. Keep implementation choices out of scope. Preserve every unresolved question that could change business behavior. Do not approve the proposal or edit files.
+
+Optional memory tools provide hints only. Never write memory or send sensitive repository content in a memory query; prefer current files and durable Wayfinder artifacts.

package/.agents/agents/specifier.md

@@ -0,0 +1,18 @@
+---
+name: specifier
+description: "Express an approved Wayfinder proposal as observable requirements and acceptance conditions."
+tools: [read_file, list_files, search_text, git_status, git_diff, memory_search, memory_get]
+disallowedTools: [write_file, edit_file, run_process, task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 8
+permission:
+  write: deny
+  process: deny
+hidden: false
+readOnly: true
+skills: [wayfinder-specify]
+---
+
+Translate the approved proposal into uniquely identified, observable requirements. Give each requirement concrete acceptance conditions without prescribing internal structure. Flag critical ambiguity rather than filling it with an assumption. Do not design or edit files.
+
+Memory, when exposed, is read-only optional context and never lifecycle evidence. Keep queries abstract and privacy-safe.

package/.agents/agents/verifier.md

@@ -0,0 +1,18 @@
+---
+name: verifier
+description: "Independently verify every Wayfinder requirement using repository inspection and focused commands."
+tools: [read_file, list_files, search_text, git_status, git_diff, run_process, memory_search, memory_get]
+disallowedTools: [write_file, edit_file, task, delegate, subagent, sessions_create]
+mode: subagent
+maxTurns: 14
+permission:
+  write: deny
+  process: allow
+hidden: false
+readOnly: true
+skills: [wayfinder-verify, wayfinder-test-design]
+---
+
+Verify the implementation independently. Treat progress notes as untrusted context, inspect actual files, run focused commands, and cover every requirement exactly once with concrete evidence. Independently check that each functional scenario has a happy-path and an unhappy-path test, and for UI changes that tests avoid fragile selectors and use semantic, convention-matching ids. Fail when evidence is missing, a command fails, or blockers remain. Do not edit or delegate.
+
+Optional memory cannot prove implementation state and must remain privacy-safe and read-only.

package/.agents/skills/wayfinder-archive/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: wayfinder-archive
+description: "Trigger: wayfinder archive, close change. Validate complete artifacts, units, requirements, and passing verification."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load only after independent verification passes.
+
+## Hard Rules
+
+- Require the exact artifact inventory supplied by the coordinator.
+- Require every unit and requirement exactly once.
+- Report blockers rather than repairing or archiving anything.
+- Never mutate files, state, or lifecycle phase.
+
+## Decision Gates
+
+| Condition | Readiness |
+| --- | --- |
+| Artifact missing or unreadable | Not ready |
+| Unit incomplete | Not ready |
+| Verification absent or failed | Not ready |
+| All inventories match | Ready |
+
+## Execution Steps
+
+1. Inspect required artifact presence.
+2. Reconcile completed unit and requirement inventories.
+3. Confirm passing verification is present.
+4. Return the exact readiness JSON.
+
+## Output Contract
+
+Return readiness, exact artifacts, units, requirements, blockers, and summary.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-coordinate/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: wayfinder-coordinate
+description: "Trigger: wayfinder status, resume wayfinder, wayfinder lifecycle. Operate deterministic commands without bypassing gates."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load when starting, inspecting, or resuming a Wayfinder change.
+
+## Hard Rules
+
+- Treat command code and validated state as lifecycle authority.
+- Never approve proposal or plan scope on the user's behalf.
+- Never hand-edit lifecycle state or generated phase artifacts.
+- Do not delegate; phase commands create bounded sessions directly.
+
+## Decision Gates
+
+| State | Action |
+| --- | --- |
+| No change | Run `new` with explicit intent |
+| Critical questions | Record clarification, then retry |
+| Approval pending | Ask concisely or stop headless |
+| Implementation | Build one unit |
+| Verification/archive | Use the indicated command |
+
+## Execution Steps
+
+1. Read status before resuming unfamiliar work.
+2. Run only the reported next command.
+3. Surface blocked state and artifact path without inventing a transition.
+4. Retry the same phase after malformed or partial child output.
+
+## Output Contract
+
+Return change name, current phase, blocking gate, and exact next command.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: wayfinder-design
+description: "Trigger: wayfinder design, technical approach. Choose a lean repository-aligned design for the full specification."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load for technical design after a complete specification exists.
+
+## Hard Rules
+
+- Satisfy every requirement without expanding approved scope.
+- Prefer existing patterns and minimal dependencies.
+- Record rationale and material risks for each meaningful choice.
+- Do not edit, execute, plan units, or delegate.
+
+## Decision Gates
+
+| Choice | Preference |
+| --- | --- |
+| Existing pattern fits | Reuse it |
+| New dependency proposed | Justify maintenance value |
+| Risk affects acceptance | Make mitigation explicit |
+
+## Execution Steps
+
+1. Inspect relevant architecture and tests.
+2. Select the smallest maintainable approach.
+3. Name expected relative paths.
+4. Return decisions, paths, and risks in the requested JSON.
+
+## Output Contract
+
+Return summary, non-empty decisions, expected paths, and risks.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-discover/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: wayfinder-discover
+description: "Trigger: wayfinder discovery, inspect change context. Gather repository facts and critical questions without designing."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load for the discovery phase of one explicit change intent.
+
+## Hard Rules
+
+- Cite current repository evidence, not guesses.
+- Keep product, security, data, and compatibility uncertainty visible.
+- Do not propose implementation or mutate files.
+- Return only the coordinator-requested JSON shape.
+
+## Decision Gates
+
+| Finding | Treatment |
+| --- | --- |
+| Confirmed in files | Record as finding or constraint |
+| Changes business behavior | Record as critical question |
+| Merely technical risk | Preserve for design context |
+
+## Execution Steps
+
+1. Locate repository structure, conventions, and relevant tests.
+2. Inspect only paths connected to the intent.
+3. Separate constraints from open questions.
+4. Produce a concise evidence-based summary.
+
+## Output Contract
+
+Return summary, non-empty findings, constraints, and critical questions.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-implement/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: wayfinder-implement
+description: "Trigger: wayfinder implement, build work unit. Implement one approved unit and provide successful command evidence."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load for exactly one pending unit from an approved plan.
+
+## Hard Rules
+
+- Change only what the unit requires.
+- Cover each functional scenario with a happy-path and an unhappy-path test, and report `testDesign`.
+- For UI changes, report `testability` with semantic `feature-element-variant` ids, or an `accessibleOnlyReason`.
+- Under strict TDD, write the failing test first, capture the failing run, then make it pass.
+- Never fabricate a failing run, and never change production code merely to satisfy a check.
+- For a `test-strengthening` unit, edit test files only; never change production code.
+- Never edit `.alisio/wayfinder` lifecycle files.
+- Run focused commands and report only successful evidence.
+- Return explicit changed paths; self-report alone is not completion.
+- Do not delegate.
+
+## Decision Gates
+
+| Situation | Action |
+| --- | --- |
+| Scenario has several valid variants | Add one happy plus one alternative |
+| Invalid input, failing dependency, permission, boundary | Add an unhappy-path test |
+| UI element has no meaningful text | Add a semantic `data-testid` |
+| UI element has role and accessible name | Query by role/name; no test id |
+| Unit cannot be completed safely | Stop without claiming completion |
+| Check fails | Fix within scope or report failure |
+| Unrelated defect found | Leave a note; do not expand scope |
+
+## Execution Steps
+
+1. Inspect target paths and nearby conventions.
+2. Implement the smallest complete change, listing happy and unhappy scenarios.
+3. Add the tests (failing first under strict TDD); prefer accessible queries and semantic ids.
+4. Run focused checks relevant to the unit.
+5. Return the exact structured evidence contract.
+
+## Output Contract
+
+Return unit ID, summary, non-empty changed paths, passed command evidence, `testDesign` entries `{ scenario, happy[], unhappy[] }`, `testability` for UI changes, and notes.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-mutate/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: wayfinder-mutate
+description: "Trigger: wayfinder mutate, mutation testing, surviving mutants. Run bounded already-installed mutation tooling and triage survivors."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load when the coordinator asks for one bounded mutation run on a change's own scope.
+
+## Hard Rules
+
+- Run only the supplied argument list; never install tooling or add dependencies.
+- Never edit files or change production behavior to kill mutants.
+- Never build a shell command from file content or survivor text.
+- Mark a survivor equivalent only with a concrete justification.
+- Report at most the bounded survivor count and an honest mutation score.
+
+## Decision Gates
+
+| Signal | Action |
+| --- | --- |
+| Tooling is missing | Return a result stating it is unavailable; do not install |
+| Survivor is unreachable or equivalent | Set `equivalent: true` and justify it |
+| Survivor reflects weak tests | Leave it non-equivalent |
+| Command fails to run | Report the failure in the summary |
+
+## Execution Steps
+
+1. Confirm the supplied tool is already available; never install.
+2. Run the exact argument list once with the given bounds.
+3. Collect survivors and classify each as equivalent or failing.
+4. Return the bounded result JSON.
+
+## Output Contract
+
+Return the tool, stack, bounded survivors with equivalence and justification, the mutation score when reported, and a summary.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-plan/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: wayfinder-plan
+description: "Trigger: wayfinder plan, implementation units. Create ordered work units with complete requirement coverage."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load when specification and design are complete.
+
+## Hard Rules
+
+- Cover every requirement in at least one work unit.
+- Keep each unit independently understandable and verifiable.
+- Include expected paths and focused checks.
+- Set `requiresTests: true` for units that must carry tests, and note expected testable anchors for UI units.
+- Mark `tddExempt: true` only for units that cannot be test-first, and always give a non-empty `tddExemptReason`.
+- Do not edit files or approve the resulting plan.
+
+## Decision Gates
+
+| Unit shape | Action |
+| --- | --- |
+| Multiple unrelated outcomes | Split it |
+| No focused verification | Add a check |
+| Requirement uncovered | Add or revise a unit |
+| Functional behavior | Set `requiresTests: true` |
+| UI screen or interactive flow | Note expected testable anchors |
+| Cannot be test-first | Set `tddExempt: true` with a justification |
+
+## Execution Steps
+
+1. Order units by real dependency.
+2. Assign sequential `UNIT-NNN` identifiers.
+3. Map requirement IDs explicitly and set `requiresTests` for functional units.
+4. Note expected testable anchors for UI units.
+5. Confirm complete coverage before returning JSON.
+
+## Output Contract
+
+Return ordered units with title, goal, requirements, paths, checks, `requiresTests`, and expected testable anchors.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-propose/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: wayfinder-propose
+description: "Trigger: wayfinder proposal, define change scope. Produce an approval-ready outcome and explicit boundaries."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load after discovery has no unresolved critical question.
+
+## Hard Rules
+
+- Define WHAT outcome is proposed, not internal implementation.
+- Make in-scope and out-of-scope boundaries explicit.
+- Preserve consequential assumptions as critical questions.
+- Never approve the proposal or edit files.
+
+## Decision Gates
+
+| Condition | Action |
+| --- | --- |
+| Intent and evidence agree | State the bounded outcome |
+| Scope is ambiguous | Add a critical question |
+| Nice-to-have is unnecessary | Put it out of scope |
+
+## Execution Steps
+
+1. Reconcile intent with discovery constraints.
+2. State one outcome a reviewer can approve.
+3. Define boundaries and assumptions.
+4. Return the exact JSON contract.
+
+## Output Contract
+
+Return outcome, in-scope items, out-of-scope items, assumptions, and critical questions.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-specify/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: wayfinder-specify
+description: "Trigger: wayfinder specification, acceptance requirements. Convert approved scope into observable requirements."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load only after explicit proposal approval.
+
+## Hard Rules
+
+- Use sequential `REQ-NNN` identifiers.
+- Give every requirement at least one observable acceptance condition.
+- Avoid architecture and file-level prescriptions.
+- Block on ambiguity that changes expected behavior.
+
+## Decision Gates
+
+| Statement | Action |
+| --- | --- |
+| Observable behavior | Make it a requirement |
+| Verification detail | Make it acceptance criteria |
+| Internal choice | Leave it for design |
+| Business ambiguity | Add a critical question |
+
+## Execution Steps
+
+1. Cover the entire approved scope.
+2. Remove duplicate or overlapping requirements.
+3. Make acceptance conditions concrete.
+4. Return only the requested JSON.
+
+## Output Contract
+
+Return unique requirements and critical questions.
+
+## References
+
+- `../../../README.md`

package/.agents/skills/wayfinder-test-design/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: wayfinder-test-design
+description: "Trigger: test design, happy path, unhappy path, negative testing, data-testid, UI testability. Design positive/negative tests and stable UI selectors."
+license: MIT
+metadata:
+  author: alisio-contributors
+  version: 1.0
+---
+
+## Activation Contract
+
+Load when planning, implementing, or verifying functional tests, or when a unit changes UI paths.
+
+## Hard Rules
+
+- Cover every functional scenario with at least one happy-path (positive) test and one unhappy-path (negative, error, boundary, or valid-alternative) test.
+- Derive scenarios from requirements and use cases (functional black-box), combinable with white-box path coverage.
+- Query the UI as a user would: role/accessible name > label > placeholder > visible text/display value > alt/title > `data-testid` last.
+- Name ids `feature-element-variant` (for example `login-email-input`); stable, semantic, never random or internal-detail based.
+- Follow the project's existing convention (`data-cy`, `data-test`, or a typed `test-ids` module) instead of inventing a competing one.
+- Never anchor tests on implementation classes or deep DOM chains (`div > section > div:nth-child(3)`); never use copy/i18n text as the primary anchor.
+- Keep ids out of business logic; when the project strips them at build, follow that flag.
+
+## Decision Gates
+
+| Situation | Action |
+| --- | --- |
+| Scenario has several valid variants | Add one happy plus one alternative |
+| Invalid input, failing dependency, permission, boundary | Add an unhappy-path test |
+| Element has a role and accessible name | Query by role/name; no test id |
+| Element has no meaningful text (icon, wrapper, dynamic row) | Add a semantic `data-testid` |
+| Project standardizes a test attribute | Use it and the project's id module |
+
+## Execution Steps
+
+1. List functional scenarios from requirements and use cases.
+2. For each scenario, name at least one happy and one unhappy test.
+3. Prefer accessible queries; add `data-testid` only where semantics cannot carry the query.
+4. Name ids `feature-element-variant` and centralize them if the project already does.
+5. Report scenario coverage, test names, and any test ids used.
+
+## Output Contract
+
+Return `testDesign` entries `{ scenario, happy[], unhappy[] }` and, for UI changes, `testability` `{ testIds[], accessibleOnlyReason? }`. Accessibility comes first; a test id never substitutes for a correct role or accessible name.
+
+## References
+
+- `../../../README.md`