@use-the-fork/spindle 0.0.0-stage → 0.0.1

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: int-subagent-driven-dev
+description: "This is an internal skill do not load it unless explicitly required by the user or another skill."
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.4.0
+---
+
+# Subagent-Driven Development
+
+The controller coordinates a feature's tickets, workers, checks, reviews, and completion. The feature workspace and `sdd.json` are the source of truth for structured ticket and delivery state; each ticket Markdown file holds its requirements, acceptance criteria, and discussion.
+
+Use the existing checkout and preserve user changes and report history. TDD is optional; write appropriate tests and record verification evidence. Load and follow `int-verification-before-completion` before claiming work is complete. Serialize implementation and fixes, and keep implementation edits frozen while a review batch is running.
+
+## Workflow map
+
+Before acting on each chart node, announce `Step <node ID> - <node label>`, including initial entries, resumed steps, and loop re-entries. After each decision, state its result and selected branch before entering the target node.
+
+```mermaid
+flowchart TD
+    A[Restore feature state and readiness] --> B{Ready ticket available?}
+    B -- Yes --> C[Claim, implement, verify, submit, close ticket]
+    C --> A
+    B -- No --> D{All tickets closed?}
+    D -- No --> E[Resolve prerequisites or record blocker]
+    E --> A
+    D -- Yes --> F[Run feature checks]
+    F --> G{Checks current and passing?}
+    G -- No --> K[Correct feature-level work]
+    G -- Yes --> H[Request comprehensive feature review]
+    H --> I{Blocking finding?}
+    I -- Linked ticket --> J[Resume ticket work after review batch]
+    J --> A
+    I -- Feature-level --> K
+    K --> L
+    I -- No --> L{Finish gates pass?}
+    L -- No --> A
+    L -- Yes --> M[Finish feature]
+```
+
+## Ticket workflow
+
+1. Read the feature spec, tickets, applicable instructions, glossary, and ADRs. Inspect `spindle sdd status --spec <path>` and `spindle sdd ready --spec <path>` to understand blockers, dependencies, and available work.
+2. Create a ticket for independently actionable work with `spindle sdd ticket create`. Fill its `[REQUIREMENTS]` and `[ACCEPTANCE CRITERIA]` placeholders. Use `spindle sdd ticket update` for tracker status, explicit blockers, and dependencies; the supported lifecycle is `open`, `in-progress`, and `closed`. Readiness is derived from status, blockers, and dependencies rather than stored as a separate triage state.
+3. Claim a ready ticket with `spindle sdd claim`. Dispatch implementation with `spindle sdd implement`; pass the worker the exact assignment and report destination. Submit its report with `spindle sdd submit --role implementation`.
+4. Run relevant tests and checks and record their actual outcomes against the current snapshot. TDD is not required, but verification is.
+5. Address implementation and verification gaps, then close the ticket with `spindle sdd ticket update --status closed` once its acceptance criteria are met. Do not use per-ticket accept or integrate steps.
+
+If work is interrupted, inspect `spindle sdd status` and use `spindle sdd resume` to restore the recorded assignment. Preserve existing reports, findings, and evidence. Do not invent missing results or reset progress.
+
+## Feature review and completion
+
+After every ticket is closed, establish current feature-level checks and request the comprehensive review with `spindle sdd review --scope delivery --inventory <json-array>`. The `sdd-reviewer` is the default reviewer. Add specialists only for justified objectives with `spindle sdd review require --scope delivery --type <agent-name>`; eligible names must be marked `canReview: true` in the Blueprint Catalog, and actual agent access must be confirmed before dispatch.
+
+Submit every assigned review report against its exact assignment. Register findings from their report and snapshot. A blocking finding can name `--related-ticket`; once the complete review batch is submitted, that ticket is reopened so work can resume. Resolve blocking findings through ticket work and repeat any invalidated checks and reviews.
+
+For detailed review, findings, correction, and finish steps, read [feature delivery](./references/full-spec.md). For feature-level corrective work, follow [corrective rounds](./references/corrective-rounds.md). Feature completion requires all tickets closed, current passing required checks and reviews, and no unresolved delivery blockers. Use the normal Git workflow; SDD does not stage, commit, or publish work and has no per-ticket integration command.
+
+## Reports and verification
+
+Keep worker reports at their assigned absolute paths inside the feature's `reports/` directory. Preserve earlier reports as history and distinguish inspected evidence from checks actually run. Record failures, unavailable checks, and limitations explicitly. A passing test run is not a substitute for review or for the acceptance criteria.
+
+See [verification evidence](./references/verification-evidence.md) for the worker handoff contract.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/assets/implementer-prompt.md

@@ -0,0 +1,40 @@
+# Template
+
+```md
+## Assignment
+
+Implement ticket: [TICKET_ID]
+Checkout: [CHECKOUT]
+Mode: [INITIAL_OR_CORRECTIVE]
+
+## Requirements and starting state
+
+Canonical ticket, comments, and spec/brief:
+[ABSOLUTE_SOURCE_POINTERS]
+
+Acceptance criteria and confirmed test seams:
+[CRITERIA_AND_SEAMS]
+
+Completed dependencies and starting snapshot:
+[DEPENDENCIES_AND_SNAPSHOT]
+
+## Scope and permissions
+
+Allowed code, test, and `.scratch` files:
+[FILE_SCOPE]
+
+Permissions, including commit authorization:
+[PERMISSIONS]
+
+## Verification and hand-back
+
+Approved project checks and test working directory:
+[CHECKS_AND_DIRECTORY]
+
+Assigned `.scratch` report path:
+[REPORT_PATH]
+
+## Correction context (CORRECTIVE only; omit for INITIAL)
+
+[ROUND, FINDING_IDS, PRIOR_ATTEMPTS, AND RULINGS, INLINE OR READ_REQUIRED_REFERENCE]
+```

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/assets/reviewer-prompt.md

@@ -0,0 +1,43 @@
+# Template
+
+```md
+## Assignment
+
+Review scope: [INITIAL_TICKET_OR_CORRECTIVE_TICKET_OR_AGGREGATE_DELIVERY_OR_CORRECTIVE_DELIVERY]
+Mode: [INITIAL_OR_CORRECTIVE_OR_AGGREGATE]
+Implementation description and review objective:
+[DESCRIPTION_AND_OBJECTIVE]
+
+## Review inputs
+
+REVIEW_INPUTS:
+[ABSOLUTE_READ_REQUIRED_PACKAGE_REFERENCE_OR_EQUIVALENT_INLINE_INPUTS]
+
+Implementation report:
+[REPORT_FILE]
+
+Known concerns and dependencies:
+[CONCERNS_AND_DEPENDENCIES_OR_NONE]
+
+Prior findings, controller rulings, and relevant coverage:
+[PRIOR_REVIEW_STATE_OR_NONE]
+
+## Correction context (CORRECTIVE only; omit otherwise)
+
+Phase and persisted attempt:
+[PHASE_AND_ROUND]
+
+Fix-only diff, exact prior/fixed identities, and fresh covering checks:
+[FIX_INPUTS_OR_READ_REQUIRED_REFERENCE]
+
+Selected findings copied verbatim with stable IDs, or concrete check failure:
+[FINDINGS]
+
+Initial ticket/aggregate review coverage and prior Spec/Quality verdicts:
+[INITIAL_COVERAGE_AND_PRIOR_VERDICTS]
+
+## Hand-back
+
+Assigned absolute report destination:
+[REPORT_PATH]
+```

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/aggregate-review.md

@@ -0,0 +1,7 @@
+# Aggregate review scope
+
+Read for a comprehensive aggregate review before inspecting changes.
+
+Cover the entire spec and cross-task integration, including omitted required behavior and parked findings. Read relevant prior findings and controller rulings; preserve stable finding IDs and distinguish ruled findings from new regressions. Apply comprehensive Spec and Quality assessment, including correctness, tests, maintainability, and material behavior-preserving simplifications. Accepted individual tickets do not establish whole-spec coverage.
+
+**Complete when:** the report accounts for the whole assigned delivery, cross-task risks, relevant prior rulings, and any coverage limits. Return to the agent's normal report contract; acceptance remains controller-owned.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/corrective-rounds.md

@@ -0,0 +1,72 @@
+# Feature correction
+
+Parent: K - Correct feature-level work. Enter this workflow for actionable
+feature-level review findings or non-mechanical feature-check failures. A
+finding linked with `--related-ticket` returns to normal ticket work after the
+review batch reopens that ticket.
+
+Before acting on a chart node, announce
+`Step K.<node ID> - Correct feature-level work / <node label>`, including
+initial entries, resumed steps, and loop re-entries. After each decision, state
+its result and selected branch before entering the target node.
+
+```mermaid
+flowchart TD
+    A[Inspect finding, checks, and correction history] --> B{Further attempt justified?}
+    B -- Yes --> C[Record objective and dispatch correction]
+    B -- No --> X[Record blocker and pause for adjudication]
+    C --> D[Run relevant checks and record outcomes]
+    D -- Checks pass --> E[Freeze snapshot and request comprehensive review]
+    D -- Checks fail or are blocked --> A
+    E --> F{Blocking findings remain?}
+    F -- Yes --> A
+    F -- No --> Y[Return to the feature finish gate]
+```
+
+## A. Inspect finding, checks, and correction history
+
+Read the finding and its report provenance, current feature state, relevant
+checks, and previous correction attempts. Identify a concrete correction
+objective and the evidence needed to determine whether it is resolved.
+
+## B. Further attempt justified?
+
+For a first attempt, confirm the finding or check failure is actionable. For
+later attempts, cite verified progress from current checks or review. Repeated
+failures, stalled progress, or requirements disagreement require controller
+adjudication rather than another automatic dispatch.
+
+## C. Record objective and dispatch correction
+
+Use `spindle sdd correct --scope delivery` to record and dispatch the feature-level
+correction. Preserve prior attempts, reports, and report destinations.
+Serialize implementation edits and keep the assignment limited to the
+recorded objective.
+
+## D. Run relevant checks and record outcomes
+
+Run appropriate tests and checks against the corrected snapshot. Record actual
+results and limitations. Do not claim stale evidence covers changed code or
+requirements.
+
+## E. Freeze snapshot and request comprehensive review
+
+After checks pass, freeze implementation edits and request a new comprehensive
+feature review against the corrected snapshot. Submit each assigned report
+against its exact assignment.
+
+## X. Record blocker and pause for adjudication
+
+Preserve working changes, reports, findings, attempts, and evidence. State the
+remaining blocker or requirement decision needed; do not dispatch another
+correction until it is resolved.
+
+## Y. Return to the feature finish gate
+
+Record the resolved findings and current check/review evidence. Resume the
+parent with `Step K - Correct feature-level work`, then continue at
+`Step L - Finish gates pass?`. If adjudication was required at X, resume at
+`Step K.B - Correct feature-level work / Further attempt justified?` only after
+the blocker or decision is resolved. TDD is optional; tests appropriate to the
+change remain expected, and verification evidence must be recorded before
+completion.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/example-workflow.md

@@ -0,0 +1,25 @@
+# Example feature workflow
+
+This example shows a small feature with two dependent tickets. The ticket
+Markdown holds requirements and acceptance criteria; `sdd.json` holds tracker
+status and dependencies.
+
+1. Create a feature workspace and split independent work into tickets:
+   `spindle sdd create`, then `spindle sdd ticket create` for each ticket.
+2. Record the dependency with
+   `spindle sdd ticket update --ticket T-0002 --blocked-by T-0001`. Check `spindle sdd ready`:
+   the prerequisite is ready and the dependent ticket is not.
+3. Claim and implement `T-0001`, submit its report, run and record relevant
+   checks, then close it with `spindle sdd ticket update --status closed`.
+4. `T-0002` becomes ready because its dependency is closed. Implement and
+   verify it in the same way, then close it.
+5. Record current feature-level required checks and request the comprehensive
+   review with `spindle sdd review --scope delivery`. Add only justified specialists.
+6. Submit every assigned report. Register findings from their report and
+   snapshot. A blocking finding can reopen its related ticket; complete the
+   correction, close the ticket again, and refresh stale checks and review.
+7. Finish when every ticket is closed, all required checks and reviews pass on
+   the current feature snapshot, and no delivery blockers remain.
+
+Use the normal Git workflow for code. There is no per-ticket accept or
+integration step; the SDD CLI does not stage or commit changes.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/full-spec.md

@@ -0,0 +1,72 @@
+# Feature delivery
+
+Feature delivery is the completion gate for one feature workspace. It begins
+after every ticket is closed; it does not replace ticket-level implementation or
+acceptance criteria. Use `--scope delivery` instead of `--ticket` for feature
+checks, review assignments, findings, and corrections.
+
+## Checks and review
+
+Inspect `spindle sdd status --spec <spec>` and `spindle sdd next --spec <spec>`. Establish
+required final checks with `spindle sdd checks require --scope delivery`, run them, and
+record actual results against the returned snapshot. Then dispatch the
+comprehensive review with
+`spindle sdd review --scope delivery --inventory <json-array>`. Its inventory must
+cover the feature's current Git-derived changes.
+
+The `sdd-reviewer` is the default comprehensive reviewer. Before dispatch,
+record any justified specialist with
+`spindle sdd review require --scope delivery --type <agent-name> --details <objective>`.
+Only catalog agents with `canReview: true` are eligible. Confirm that the
+controller can actually dispatch each selected agent; catalog eligibility does
+not guarantee harness access.
+
+Preserve each assignment's ID, objective, snapshot, inventory, and report
+path. Submit every report against its exact assignment. A missing, pending,
+failed, unavailable, stale, or mismatched review blocks completion.
+
+## Findings and correction
+
+Register findings from their assigned reports and snapshots with
+`spindle sdd finding create --scope delivery`. Delivery findings have feature-scoped
+IDs, provenance, ruling history, and status. Use `--related-ticket <id>` for a
+finding that should return work to a specific ticket. A blocking linked finding
+reopens its ticket after the complete review batch is submitted; dependent
+tickets remain blocked until that ticket is closed again.
+
+Use `spindle sdd finding update --scope delivery` for explicit rulings. Deferring a
+blocker requires rationale, a follow-up reference, and an approved delivery
+requirements decision. Record that decision with
+`spindle sdd requirements decide --scope delivery` only after a requirements change
+and completed prior review. Approval invalidates earlier aggregate assignments.
+
+For actionable feature findings, follow [feature correction](./corrective-rounds.md)
+and use `spindle sdd correct --scope delivery` to record
+each independent correction attempt. Record passing checks against the changed
+feature snapshot and submit the implementation report before requesting a new
+feature review. Pause unproductive work, recurring failures, or requirements
+disagreement for adjudication. Resume with `spindle sdd resume --scope delivery`;
+preserve existing assignments, attempts, evidence, and adjudication.
+
+## Finish
+
+Use the normal Git workflow for code changes. SDD does not stage, commit,
+publish, or require a per-ticket integration confirmation. A changed code or
+requirements snapshot invalidates evidence that no longer covers it.
+
+Legacy feature workspaces without a recorded Git baseline stay blocked until
+the original comparison baseline is identified. Do not silently use the
+current `HEAD` after implementation; that could omit completed feature work
+from review.
+
+Finish with `spindle sdd finish --spec <spec> --author <author>`. Completion requires
+at least one ticket, every ticket closed, current passing required feature
+checks and reviews, and no unresolved delivery blockers. The retrospective
+policy is stored at feature creation: when required, attach a Markdown report
+with `--report`; otherwise it is optional. Any report must remain inside that
+feature's `reports/` directory.
+
+Use `spindle sdd status`, `spindle sdd next`, and
+`spindle sdd resume --scope delivery` to inspect blockers and
+restore interrupted feature-level work. These commands do not close tickets or
+publish changes.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/implementer-corrections.md

@@ -0,0 +1,9 @@
+# Corrective implementation inputs
+
+Read only for a corrective implementation assignment, before accepting its gate.
+
+Require a concrete `SCOPE` (`ticket` or `delivery`), `ROUND`, and assigned `FINDING_IDS`, plus `PRIOR_ATTEMPTS` and `RULINGS` supplied or explicitly `NONE`. Initial assignments do not require these fields. Accept values through an explicit, read-required correction-context reference or inline equivalent structured fields. Ticket 08 establishes this contract for ticket scope. Ticket 10 introduces delivery-scoped operations and must reuse the contract with independent delivery attempts, rulings, and evidence; until then the current CLI accepts ticket scope only.
+
+Read every assigned finding and relevant prior attempt/ruling before editing. Resume the supplied snapshot and test status; the controller owns progress assessments and dispatch decisions. Correct the complete assigned batch within file scope and verify fresh covering tests. Preserve prior report history; attempt numbers are not a fixed retry allowance.
+
+**Complete when:** all branch inputs are supplied and consistent; otherwise return `NEEDS_CONTEXT` with specific missing inputs before creating a report. After fixing, include each finding's correction and current covering-test evidence in the implementer report.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/review-inputs.md

@@ -0,0 +1,26 @@
+# Review inputs
+
+Read when preparing or accepting a review assignment. The controller supplies these inputs once per frozen review batch; all reviewers consume the same change and verification identity. A durable review-package reference is a transport for existing inputs, not a new artifact generator or a replacement for provenance.
+
+## Common input contract
+
+`REVIEW_INPUTS` names an absolute, read-required package/manifest path. Read it and its required sources before inspecting the checkout or reviewing. Equivalent structured inputs inline remain valid; preserve supplied values rather than inferring missing revisions from Git.
+
+| Input                  | Required meaning                                                                                                                                                                                                                          |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Requirements           | Canonical ticket/spec/comments pointers, applicable instructions, criteria, and constraints. Identify inapplicable sources explicitly.                                                                                                    |
+| Workspace and snapshot | Absolute shared checkout; exact reviewed identity, comparison base and head revisions, and included dirty/untracked changes or `NONE`. SHAs are provenance metadata and may live in the package rather than repeated prompt fields.       |
+| Complete change        | Complete assigned diff with file inventory, stat, and enough context, or approved read-only retrieval using supplied revisions. Include dirty/untracked additions and binary changes, or identify unavailable material as a coverage gap. |
+| Verification           | Commands, results, test summary, exact snapshot covered, and unavailable required checks. Evidence pointers are valid; read them before judging coverage.                                                                                 |
+
+Keep every meaning authoritative in one place: reference canonical requirements, reports, and evidence rather than copying full logs or the entire ledger. A pointer must identify the required material, not merely say "see ledger". The role-specific assignment supplies phase, objective, history relevant to that role, and its distinct report destination.
+
+## Snapshot ownership and completeness
+
+The controller owns construction, freezing, and freshness checks. Reuse existing durable complete diffs and evidence; no additional packaging command or hash scheme is required. The identity must distinguish uncommitted/untracked content, not just HEAD. Keep implementation frozen throughout the review batch, allowing assigned report writes without changing the reviewed code identity.
+
+Corrections produce a new reviewed identity with fresh covering checks. Preserve the previous package and evidence as history rather than relabeling them as verification of changed code.
+
+Reviewers inspect the supplied change and enough matching surrounding code to support their role. Complete supplied diffs take precedence over independently reconstructing Git ranges. Legacy revision-based assignments remain valid: retrieve missing diffs only with approved read-only tooling and supplied revisions, accounting for supplied dirty/untracked changes. Missing or inconsistent inputs require `NEEDS_CONTEXT` before review; required evidence that is stale, failing, or unavailable prevents approval. If surrounding code no longer matches the assigned snapshot, report the mismatch to the controller.
+
+**Assignment complete when:** required inputs are resolved and consistent, including a precise review scope and report destination. **Review evidence sufficient when:** the diff covers the assigned change and required passing checks cover that same snapshot. These are distinct gates; supplied claims are not proof of correctness.

package/build/Assets/Blueprints/skills/int-subagent-driven-dev/references/verification-evidence.md

@@ -0,0 +1,7 @@
+# Test and verification handoff
+
+The implementer follows repository test guidance and writes or updates tests appropriate to the assigned behavior. SDD does not require test-first sequencing or proof of an initial failure.
+
+The report records relevant commands and results, the tested snapshot, failures, and checks not run. Distinguish evidence run by the implementer from evidence supplied by the controller. Formatting, lint, type checks, and ticket-wide regression checks belong to the controller unless explicitly assigned to the worker.
+
+On resume, use `int-verification-before-completion` to determine whether evidence is current and sufficient. Missing, stale, ambiguous, or failing required evidence remains unresolved; it is not success-shaped completion.

package/build/Assets/Blueprints/skills/int-test-driven-development/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: int-test-driven-development
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.2.0
+---
+
+# Test-Driven Development
+
+Reference for TDD sequencing and test quality. Implementers apply the relevant procedure within their assigned workflow; reviewers assess tests and supplied evidence without implementing or starting a TDD cycle. The caller owns task sequencing, permissions, check scheduling, and delivery.
+
+Read the relevant glossary and ADRs so test vocabulary and boundaries match the domain.
+
+## Behavior and seam
+
+A test observes behavior through the module's interface at a **seam**. Reuse confirmed seams recorded in the assignment when unchanged. For missing or changed seams, propose the interface and what it catches and misses; obtain confirmation before writing tests there. Dispatched workers request clarification or approval through the controller; otherwise ask the user.
+
+Testing is ready when the expected behavior is clear and the seam has applicable confirmation. Work stays within the assigned scope.
+
+## Behavior changes and bug fixes
+
+1. **Write a cohesive test batch** at the agreed seam. Group one operation's happy path, validation, and edge cases; keep each test focused on one behavior and unrelated operations in separate batches. Use behavior cohesion, not an arbitrary test count, to bound the batch.
+2. **Verify RED together.** Run the batch in one approved runner invocation and confirm an intended behavioral failure for every new test before implementation. A nonzero exit alone is insufficient. Repair setup errors before evaluating RED. If a test passes, investigate existing behavior or an insensitive test; never delete working code to manufacture failure. If the runner skips tests or stops early, obtain the missing RED evidence before proceeding.
+3. **Implement minimally.** Change only what satisfies the current behavior group.
+4. **Verify GREEN together.** Run the batch and relevant regression tests, combining related selectors in one approved runner invocation where supported; correct failures before the next batch. Use individual runs only when needed to diagnose failures or establish missing evidence.
+
+Work in cohesive vertical slices: reach GREEN for the current behavior group before starting the next unrelated group. Do not default to a separate RED/GREEN cycle for each test. Each requested behavior needs coverage, with relevant tests passing on the final implementation.
+
+## Pure refactors
+
+Start from passing relevant tests, make the structural change, then rerun those same tests. No RED phase is required. Reuse adequate coverage; if it cannot protect the affected behavior, add passing characterization coverage within the assigned scope before refactoring. Preserve behavioral assertions; fix regressions rather than weakening them. Observable behavior changes take the RED → GREEN path.
+
+Keep small necessary local refactors after GREEN; substantial cleanup requires a review finding or explicit refactoring ticket.
+
+Relevant tests must pass again and the diff must preserve tested behavior.
+
+## Test quality
+
+- Assert public behavior, not private methods or internal collaborator calls.
+- Derive expected values independently from the spec, a known-good literal, or a worked example, not the production algorithm.
+- Keep tests meaningful through behavior-preserving structural changes.
+
+When adding or changing tests, or reviewing their quality, read [Writing good tests](./references/tests.md). When choosing or assessing test doubles, read [Mocking and test doubles](./references/mocking.md).
+
+## Review and test evidence
+
+Assess behavioral coverage and available RED/GREEN evidence within the review assignment. A concise test summary and fresh GREEN results suffice; missing archived RED logs alone do not block approval. Current GREEN establishes present behavior, not historical test order. Disclose a skipped test-first step honestly; preserve working code rather than manufacturing historical RED.
+
+Use the `int-verification-before-completion` skill for evidence attribution, scope, freshness, and completion claims. The caller defines required checks and their authorized owner; this reference does not schedule checks or grant permission to run them.

package/build/Assets/Blueprints/skills/int-test-driven-development/references/mocking.md

@@ -0,0 +1,31 @@
+# Mocking and Test Doubles
+
+A test double replaces a real dependency to isolate behavior or control an external effect. Use one when it makes a test more reliable or focused—not merely because the dependency is present.
+
+## Prefer real application components when practical
+
+Use real code for the behavior under test and its ordinary collaborators when that keeps the test fast and reliable. Prefer a test database over mocking database queries when testing persistence.
+
+Use a mock, fake, or stub when a dependency is external, slow, nondeterministic, expensive, or needs to produce a controlled failure. Examples include an external API, email provider, clock, or random-number source.
+
+## Double the boundary, not the behavior under test
+
+Keep the component being tested real. Replace only the dependency that needs isolation, and preserve any real side effects the test relies on.
+
+Before replacing a dependency, understand what the real operation does. A mock that skips a required write, state change, or callback can make a test pass while the application behavior is broken.
+
+When testing an interaction with an external system, assert the interaction if it is part of the contract—for example, that the application sends the expected amount to a payment provider. Do not assert calls, counts, or ordering merely because the test can observe them.
+
+## Keep test doubles realistic
+
+Give doubles behavior and data that match the dependency's documented contract. Include the fields downstream code relies on, and use separate setups for meaningfully different outcomes such as success, failure, or malformed data.
+
+Avoid generic doubles that accept any input or return a success-shaped default. They can hide incorrect arguments and unhandled error cases.
+
+## Prefer simpler tests over elaborate mocks
+
+If a test needs many mocks, conditional mock behavior, or complicated setup, consider whether an integration test with real components would be clearer and more reliable.
+
+Use dependency injection or a small adapter when it naturally isolates an external boundary. Do not complicate production design solely to make internal collaborators easier to mock.
+
+Test-only setup and cleanup belong in test helpers. Keep production classes responsible for production behavior and lifecycle.

package/build/Assets/Blueprints/skills/int-test-driven-development/references/tests.md

@@ -0,0 +1,68 @@
+# Writing Good Tests
+
+A useful test catches a plausible bug in behavior that matters. It should describe a contract clearly enough that someone can understand what would break if it failed.
+
+## Name the behavior the test protects
+
+Before writing a test, ask: **What realistic production change should make this test fail?**
+
+Good candidates include a wrong branch, missing validation, incorrect result, or missing side effect. Test behavior callers rely on—not a particular implementation choice.
+
+Prefer a test name that describes the behavior:
+
+The examples below are pseudocode.
+
+```text
+TEST "rejects an expired invitation"
+  invitation = expired invitation fixture
+  ASSERT accepting invitation rejects it as expired
+END TEST
+```
+
+Avoid names that merely describe the code under test:
+
+```text
+TEST "calls validateInvitation"
+  accept invitation
+  ASSERT validateInvitation was called
+END TEST
+```
+
+## Choose an appropriate boundary
+
+Test through the interface that best demonstrates the contract:
+
+- Use a unit test for focused logic with a clear input and output.
+- Use an integration test when behavior depends on collaborating components, persistence, or framework wiring.
+- Use an end-to-end test when the user-visible flow itself needs verification.
+
+Prefer public interfaces over private methods or implementation details. A database assertion can be appropriate when persistence is part of the behavior being tested; avoid querying storage merely to inspect internal details unrelated to the contract.
+
+Test behavior owned by this application, not framework mechanics that the framework itself guarantees. If an upstream behavior is surprising and important to rely on, a narrow characterization test can document that assumption.
+
+## Keep expectations independent
+
+Expected values should come from the requirement, a known result, or a hand-checked fixture—not from the code under test or the same logic it uses.
+
+```text
+TEST "totals item prices"
+  items = two items priced 10 and 5
+  ASSERT calculateTotal(items) EQUALS 15
+END TEST
+```
+
+Avoid calculating the expected result with the same algorithm as the implementation. That can let the same mistake appear on both sides of the assertion.
+
+## Keep each test focused
+
+A test should explain one behavior. It may need several assertions to describe that behavior fully; split it when the assertions cover distinct outcomes or unrelated responsibilities.
+
+Use small, meaningful fixtures. Include the fields and relationships the real contract requires, and choose values that make incorrect behavior visible.
+
+Cover important alternate paths and boundaries, such as invalid, empty, unauthorized, or missing input when those cases matter to the contract. Do not add a test for every function or line just to mirror the implementation.
+
+## Check that the test can catch a bug
+
+Before finishing, consider a plausible incorrect change: a missing validation, wrong return value, omitted state change, or incorrect branch. Would this test fail?
+
+If not, strengthen the test around the behavior that matters. Avoid tests that only prove a constant, mock, private structure, or source text has a particular shape.

package/build/Assets/Blueprints/skills/int-testing-agent-guidance/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: int-testing-agent-guidance
+metadata:
+  spindle:
+    version: 1.0.0
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+---
+
+# Testing Agent Guidance
+
+Test guidance by applying it to realistic tasks. Reading or reviewing a document alone does not show that an agent can follow it.
+
+## Core workflow
+
+Use this workflow for behavior-shaping changes to skills, agents, prompts, instructions, and documents reached by their pointers. For purely editorial changes, preserve the existing behavior and verify that meaning and references remain intact.
+
+1. **Define the behavior.** Identify the intended agent action and a checkable pass criterion. Choose an application, retrieval, or decision scenario that exercises the actual requirement.
+2. **Run the baseline before editing.** For a new document, run the scenario without the proposed guidance. For an edit, run it against the current version. Include the relevant task context, ask the agent to act rather than recite rules, and record its response. If the baseline meets the criterion, leave that behavior unchanged.
+3. **Make the smallest change.** Address the observed gap and keep each rule in one authoritative place. Do not add defenses for failures the baseline did not reveal.
+4. **Rerun the same scenario.** Use a fresh context with the full revised guidance and unchanged prompt and pass criterion. Check the observed actions or result, not just the agent's explanation.
+5. **Close observed gaps.** If the retest fails or reveals a new rationalization, make a targeted correction and rerun the same scenario. Complete when the criterion passes and no observed failure remains unresolved.
+
+| Guidance behavior         | Scenario                                         | Pass criterion                                                        |
+| ------------------------- | ------------------------------------------------ | --------------------------------------------------------------------- |
+| Retrieval or reference    | Ask for a relevant fact, then apply it           | The agent finds and correctly uses the fact                           |
+| Technique or process      | Give a concrete task with a meaningful variation | The agent follows the process and reaches the intended result         |
+| Decision or pattern       | Give a case and a counterexample                 | The agent chooses the right branch in both                            |
+| Discipline under pressure | Present a realistic temptation to skip a rule    | The agent takes the required action and does not rationalize a bypass |
+
+**Complete when:** the same frozen scenario passes against the revised guidance, or the remaining failure and validation limit are reported.
+
+## Expanded testing
+
+Use expanded testing when the user requests it or the skill is invoked with `--test`. This adds independent samples; it does not replace the core baseline and retest.
+
+1. Freeze scenario prompts and observable pass criteria before dispatch. Cover each meaningful branch. For discipline-enforcing guidance, use at least three scenarios, each combining at least three pressures such as deadline, authority, sunk cost, or exhaustion.
+2. Run five independent read-only agents against the baseline. For a new document, provide no proposed guidance; for an edit, provide the current version. Each agent runs every scenario once and reports its concrete choices and rationalizations verbatim.
+3. The authoring agent alone edits the guidance, addressing only observed failures.
+4. Retest the same scenarios and criteria with five new read-only agents, each running every scenario once with the full revised guidance. Inspect results for compliance and new rationalizations; quoted examples are not evidence of compliance.
+5. Repeat with new agents after targeted corrections. Stop when all five pass every applicable criterion without new rationalizations. If testing is blocked or any criterion still fails, report that limitation rather than claiming validation.
+
+**Complete when:** the expanded batch meets every pass criterion, or remaining failures and blocked requirements are explicit.
+
+## Scenario quality
+
+- Give the agent a real task and the complete relevant context.
+- Make the expected action observable; use concrete options when a decision must be forced.
+- Use realistic pressures only when testing resistance to bypass.
+- Freeze prompts and criteria before the baseline so the retest remains comparable.
+- Separate scenarios into fresh contexts when one result could influence another.
+
+Use the `int-writing-for-agents` skill for document structure and context-pointer principles. This skill defines how to test the resulting guidance; it does not replace artifact-specific authoring requirements.

package/build/Assets/Blueprints/skills/int-verification-before-completion/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: int-verification-before-completion
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.1.0
+---
+
+# Verification Before Completion
+
+Use this reference when reporting verification or completion claims. The caller's workflow defines required checks, permissions, and timing; this skill defines how claims track evidence.
+
+## Match claims to evidence
+
+- Identify the claim's scope: for example, a focused test, a build, a behavior, or a set of requirements.
+- Say whether evidence was **run** by you, **inspected**, or **supplied** by someone else. Attribute supplied evidence; don't imply you ran it.
+- Include the observed result and the evidence's scope. Tie it to the relevant commit or snapshot when one is identified.
+- Claim only what the evidence establishes. A focused test does not establish that the full suite passes; passing tests do not establish that a build or all requirements pass.
+- If required evidence is missing, stale, ambiguous, or failing, state what remains unverified and identify the check and authorized owner needed to resolve it.
+- Respect the caller's permissions and approved tooling. Request evidence from the authorized owner when you cannot run a required check.
+
+## Example
+
+> Controller-supplied evidence: `pnpm test --filter order-total` exited 0 with 12 tests passing on snapshot `abc123`; I did not run it. The full production build is unverified; request controller evidence for `abc123`.