@selvakumaresra/specship 0.1.3 → 0.3.0

package/dist/workflows/defaults/spec-author.yaml

@@ -0,0 +1,214 @@
+name: spec-author
+description: Author a new spec. Draft → gap-fill review → quality review → final approval → write file.
+tags: [spec, default]
+requires: [specship, git]
+
+# Worktree isolation isn't strictly needed for spec authoring (no code
+# changes) — but enabling it keeps the artifact directory under the same
+# umbrella the other spec workflows use, and a future expansion that adds
+# example-code touches stays safe.
+worktree:
+  enabled: true
+
+inputs:
+  - name: DESCRIPTION
+    description: One-line description of the feature you want to spec
+    required: true
+  - name: PARENT_DOC
+    description: Optional spec ID of an existing doc to attach the new requirements under
+    required: false
+  - name: OWNER
+    description: Owner team or person (e.g. "security", "payments-team")
+    required: false
+  - name: PRIORITY
+    description: high / medium / low
+    required: false
+
+systemPromptAppend: |
+  You are authoring a SpecShip-compatible Markdown spec. Use the
+  spec-author skill loop and references throughout this workflow.
+  The output of every node should be markdown that is ready for the
+  next stage — do NOT write the file until the `write_file` node.
+
+nodes:
+  - id: ground
+    kind: prompt
+    output_type: code_grounding
+    allowed_tools:
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_search
+      - mcp__specship__specship_files
+      - Read
+    prompt: |
+      Feature: $INPUT.DESCRIPTION
+
+      Walk the codebase to find where this feature would live:
+
+      1. Use specship_explore on terms drawn from the description to
+         surface relevant existing symbols.
+      2. Note any existing conventions, similar features, or shared
+         primitives the new spec should align with.
+      3. List candidate file paths + qualified symbol names that the
+         new implementation might touch — these become the `implementations:`
+         block of the spec.
+
+      If this is greenfield (no relevant existing code), say so explicitly
+      and propose a target directory under src/ where the implementation
+      will live.
+
+      Output: a ≤300-word grounding report — paths, conventions, and
+      candidate symbols. Do NOT write the spec yet.
+
+  - id: draft
+    kind: prompt
+    depends_on: [ground]
+    output_type: spec_draft
+    allowed_tools:
+      - mcp__specship__specship_spec
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_node
+      - Read
+    prompt: |
+      Feature: $INPUT.DESCRIPTION
+      Optional parent doc: $INPUT.PARENT_DOC
+      Optional owner: $INPUT.OWNER
+      Optional priority: $INPUT.PRIORITY
+
+      Code grounding:
+      $ground.output
+
+      Produce a complete first-draft Markdown spec following the spec-author
+      skill's `references/format.md`:
+
+      - YAML frontmatter with id/title/owner/priority (use the inputs if
+        provided; mark as `[needs review]` if not).
+      - Embedded `<!-- id: -->` markers above every heading.
+      - RFC 2119 keyword (MUST / SHOULD / MAY) in each requirement title.
+      - One concern per requirement.
+      - `## Acceptance` section with bulleted criteria, each carrying its
+        own `.A<N>` ID. Cover both happy path and failure path.
+      - Optional `implementations:` block, populated from the grounding
+        report (or empty for greenfield).
+      - Wherever the description doesn't tell you something, insert a
+        `[needs user confirmation]` marker — DO NOT invent.
+
+      Output: the full spec markdown, ready for the gap-fill review.
+
+  - id: gap_review
+    kind: approval
+    depends_on: [draft]
+    message: |
+      Draft is ready. The gap-fill questions below identify areas the
+      description didn't cover. Approve with answers (e.g. "owner: security,
+      TTL: 1h, on non-existent email: 200 OK"), or reject with feedback to
+      revise.
+
+      Draft:
+      $draft.output
+
+      Gap-fill questions for THIS draft — walk references/gap-questions.md
+      and surface only the unanswered ones (max 5):
+      [the agent fills these in based on the draft above]
+    capture_response: true
+    on_reject:
+      prompt: |
+        The draft was rejected with this feedback. Revise the draft to
+        address it. Keep all existing IDs stable so any pre-existing links
+        survive.
+
+        Feedback:
+        $gap_review.output
+      max_attempts: 3
+
+  - id: incorporate
+    kind: prompt
+    depends_on: [gap_review]
+    output_type: spec_draft
+    allowed_tools:
+      - Read
+    prompt: |
+      Apply the gap-fill answers to the draft. Replace `[needs user
+      confirmation]` markers with the user's answers where given; leave
+      others as `[needs review]` if they explicitly skipped.
+
+      Draft:
+      $draft.output
+
+      Answers:
+      $gap_review.output
+
+      Output: the updated spec markdown.
+
+  - id: quality_review
+    kind: prompt
+    depends_on: [incorporate]
+    output_type: review_findings
+    allowed_tools:
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_node
+      - mcp__specship__specship_search
+      - Read
+    prompt: |
+      Run the spec-author skill's `references/review-checklist.md` against
+      this draft and produce a structured findings list.
+
+      Updated draft:
+      $incorporate.output
+
+      Group findings into STRUCTURAL (blocks the file write), QUALITY (block
+      on critical, warn on minor), HYGIENE (warn only). For each, give:
+      line number, what's wrong, suggested fix. Don't be polite — sharp
+      signal is more useful than soft language.
+
+      If any STRUCTURAL findings exist, propose a corrected version of the
+      affected sections inline.
+
+  - id: finalize
+    kind: approval
+    depends_on: [quality_review]
+    message: |
+      Quality review complete. Approve to write the spec file, or reject to
+      revise further.
+
+      Review:
+      $quality_review.output
+
+      Final draft:
+      $incorporate.output
+    capture_response: true
+    on_reject:
+      prompt: |
+        Final approval was rejected. Revise the draft per the feedback,
+        re-run the quality review pass, and produce a new draft.
+
+        Feedback:
+        $finalize.output
+
+        Current draft:
+        $incorporate.output
+      max_attempts: 2
+
+  - id: write_file
+    kind: prompt
+    depends_on: [finalize]
+    output_type: file_path
+    allowed_tools:
+      - Write
+      - Read
+      - Bash
+    prompt: |
+      Write the approved spec to disk.
+
+      Final draft:
+      $incorporate.output
+
+      Use the `Write` tool to create `specs/<slug>.md` at the project root,
+      where `<slug>` is derived from the feature name (kebab-case, no date
+      prefix). If a file with that name already exists, APPEND the new
+      requirements to it (preserving any pre-existing content) instead of
+      overwriting; the user will resolve the merge in review.
+
+      After writing:
+      - Run `specship sync` to index the new spec.
+      - Output the relative path of the file written + a one-line note
+        about what to do next (typically: `/ss-implement <REQ-ID>`).

package/dist/workflows/defaults/spec-fix.yaml

@@ -0,0 +1,110 @@
+name: spec-fix
+description: Fix a bug surfaced as a drifted/broken spec link. Diagnose → approve → fix → verify → re-verify link.
+tags: [spec, default]
+requires: [specship, git]
+
+worktree:
+  enabled: true
+
+inputs:
+  - name: SPEC_ID
+    description: The spec ID with the drifted or broken link
+    required: true
+
+systemPromptAppend: |
+  You are fixing code so a spec's link returns to "verified" state.
+  Call specship_spec($INPUT.SPEC_ID) first to see the current state and
+  drift_axis. After fixing, call specship_link_verify({result: "pass"})
+  on each affected link before reporting done.
+
+nodes:
+  - id: diagnose
+    kind: prompt
+    output_type: diagnosis
+    allowed_tools:
+      - mcp__specship__specship_spec
+      - mcp__specship__specship_node
+      - mcp__specship__specship_explore
+      - Read
+    prompt: |
+      Spec ID: $INPUT.SPEC_ID
+
+      Call specship_spec to inspect this spec's current state. Look at:
+      - which linked_code entries are drifted, broken, or orphaned
+      - their drift_axis (spec → spec body changed; code → code changed)
+      - the spec body itself
+
+      Output: (a) which links are out-of-spec, (b) for each, what likely
+      broke (code refactor, signature change, spec edit), and (c) a
+      proposed fix.
+
+  - id: approve_fix
+    kind: approval
+    depends_on: [diagnose]
+    message: |
+      Diagnosis for $INPUT.SPEC_ID:
+
+      $diagnose.output
+
+      Approve to apply the proposed fix, or reject with guidance.
+    capture_response: true
+
+  - id: apply
+    kind: prompt
+    depends_on: [approve_fix]
+    output_type: diff
+    allowed_tools:
+      - Read
+      - Edit
+      - Write
+      - Bash
+      - mcp__specship__specship_node
+      - mcp__specship__specship_spec
+    prompt: |
+      Apply the fix proposed in the diagnosis. Follow any guidance from
+      the reviewer.
+
+      Diagnosis:
+      $diagnose.output
+
+      Reviewer feedback (if any):
+      $approve_fix.output
+
+      Output: a short list of files changed.
+
+  - id: verify
+    kind: bash
+    depends_on: [apply]
+    output_type: test_results
+    timeout: 600000
+    bash: |
+      if [ -f package.json ]; then
+        npm test
+      elif [ -f Cargo.toml ]; then
+        cargo test
+      elif [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+        python -m pytest
+      else
+        echo "no recognised test framework; skipping"
+      fi
+
+  - id: link_verify
+    kind: prompt
+    depends_on: [verify]
+    output_type: link_summary
+    allowed_tools:
+      - mcp__specship__specship_spec
+      - mcp__specship__specship_link_assert
+      - mcp__specship__specship_link_verify
+    prompt: |
+      For each link that was drifted/broken on $INPUT.SPEC_ID, now that
+      the fix has been applied and tests pass, call specship_link_verify
+      with result="pass" (or "fail" if a test failed for that link).
+
+      If a link is orphaned because the symbol moved, call
+      specship_link_assert at the new location.
+
+      Test results:
+      $verify.output
+
+      Output: one line per link with the new state.

package/dist/workflows/defaults/spec-implement.yaml

@@ -0,0 +1,150 @@
+name: spec-implement
+description: Implement an unimplemented spec. Plan → review → implement → verify → link → review → done.
+tags: [spec, default]
+requires: [specship, git]
+
+worktree:
+  enabled: true
+
+inputs:
+  - name: SPEC_ID
+    description: The spec ID to implement (e.g. REQ-AUTH-005)
+    required: true
+
+systemPromptAppend: |
+  You are implementing a specific requirement. Before editing code, call
+  specship_spec($INPUT.SPEC_ID) to see the spec body and any code it
+  already links to. After editing, call specship_link_assert with the
+  spec_id and the symbol you implemented BEFORE reporting done.
+
+nodes:
+  - id: fetch_spec
+    kind: prompt
+    output_type: spec_summary
+    allowed_tools:
+      - mcp__specship__specship_spec
+      - mcp__specship__specship_explore
+    prompt: |
+      Spec ID: $INPUT.SPEC_ID
+
+      Call specship_spec to fetch the spec. Then call specship_explore on
+      a small bag of terms drawn from the spec title and acceptance
+      criteria to find the relevant code area.
+
+      Output: a short summary (≤300 words) of (a) what the spec asks for,
+      (b) which code areas / symbols are most relevant, and (c) whether
+      any code currently claims to implement it (look at linked_code).
+
+  - id: plan
+    kind: prompt
+    depends_on: [fetch_spec]
+    output_type: plan
+    allowed_tools:
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_node
+      - mcp__specship__specship_spec
+      - Read
+    prompt: |
+      Based on this spec summary, write a concrete implementation plan:
+
+      $fetch_spec.output
+
+      The plan should list:
+      - Files to create or modify (with project-relative paths)
+      - Specific functions/methods/classes to add or change
+      - Tests to add or update
+      - Order of changes
+
+      Keep it tight (≤500 words). Do NOT edit code in this step.
+
+  - id: approve_plan
+    kind: approval
+    depends_on: [plan]
+    message: |
+      Plan ready for $INPUT.SPEC_ID. Review the plan output and approve
+      to proceed with implementation, or reject with feedback to revise.
+    capture_response: true
+    on_reject:
+      prompt: |
+        The plan was rejected with this feedback. Revise:
+
+        $approve_plan.output
+      max_attempts: 3
+
+  - id: implement
+    kind: prompt
+    depends_on: [approve_plan]
+    output_type: diff
+    allowed_tools:
+      - Read
+      - Edit
+      - Write
+      - Bash
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_node
+      - mcp__specship__specship_spec
+    prompt: |
+      Implement the approved plan. Follow it closely.
+
+      Plan:
+      $plan.output
+
+      Approval feedback (if any):
+      $approve_plan.output
+
+      When done, output a short diff summary (which files changed and why).
+
+  - id: verify
+    kind: bash
+    depends_on: [implement]
+    output_type: test_results
+    timeout: 600000
+    bash: |
+      # Run the project's test suite. The verify node's exit code drives
+      # the gating for the link node — non-zero halts the workflow.
+      if [ -f package.json ]; then
+        npm test
+      elif [ -f Cargo.toml ]; then
+        cargo test
+      elif [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+        python -m pytest
+      else
+        echo "no recognised test framework; skipping"
+      fi
+
+  - id: link
+    kind: prompt
+    depends_on: [verify]
+    output_type: link_summary
+    allowed_tools:
+      - mcp__specship__specship_link_assert
+      - mcp__specship__specship_link_verify
+      - mcp__specship__specship_spec
+    prompt: |
+      Assert spec→code links for the changes made in the implement step.
+      For each symbol that implements $INPUT.SPEC_ID (or its child
+      requirements), call specship_link_assert with the spec_id, the
+      file path, and the qualified symbol name. After each assert, if
+      tests passed in the verify step, call specship_link_verify with
+      result="pass".
+
+      Implementation diff summary:
+      $implement.output
+
+      Test results:
+      $verify.output
+
+      Output: a short list of "spec_id → file:symbol [verified|implemented]"
+      lines.
+
+  - id: final_review
+    kind: approval
+    depends_on: [link]
+    message: |
+      Implementation complete for $INPUT.SPEC_ID.
+
+      Links asserted:
+      $link.output
+
+      Approve to finalize the run (worktree is left for you to inspect
+      and merge), or reject to abandon.

package/dist/workflows/defaults/spec-relink.yaml

@@ -0,0 +1,81 @@
+name: spec-relink
+description: Re-attach an orphaned spec link after a refactor. Search for the moved/renamed symbol → approve → assert new link.
+tags: [spec, default]
+requires: [specship]
+
+worktree:
+  enabled: false
+
+inputs:
+  - name: SPEC_ID
+    description: The spec ID with an orphaned link
+    required: true
+
+systemPromptAppend: |
+  You are reattaching a spec link whose target symbol has moved or been
+  renamed. Use specship_search and specship_explore to locate the new
+  symbol; do NOT edit code in this workflow.
+
+nodes:
+  - id: present_orphan
+    kind: prompt
+    output_type: orphan_summary
+    allowed_tools:
+      - mcp__specship__specship_spec
+    prompt: |
+      Spec ID: $INPUT.SPEC_ID
+
+      Call specship_spec to find the orphaned link(s). For each:
+      output its old target_file_path and target_qualified_name plus
+      a short description of what the spec asks for.
+
+  - id: search_candidates
+    kind: prompt
+    depends_on: [present_orphan]
+    output_type: candidates
+    allowed_tools:
+      - mcp__specship__specship_search
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_node
+    prompt: |
+      The orphan(s):
+      $present_orphan.output
+
+      For each orphaned target_qualified_name, use specship_search to
+      see if a symbol by that name (or a closely related name) exists
+      anywhere in the current codebase. Then call specship_explore on
+      the most likely matches to see if their bodies match the spec's
+      intent.
+
+      Output: a numbered list of CANDIDATES with file:symbol and a
+      one-line justification.
+
+  - id: approve_relink
+    kind: approval
+    depends_on: [search_candidates]
+    message: |
+      Candidates for $INPUT.SPEC_ID:
+
+      $search_candidates.output
+
+      Reply with the number of the correct candidate (or "none" to
+      abandon and leave the link orphaned).
+    capture_response: true
+
+  - id: assert_link
+    kind: prompt
+    depends_on: [approve_relink]
+    output_type: link_summary
+    allowed_tools:
+      - mcp__specship__specship_link_assert
+    prompt: |
+      The reviewer chose candidate #$approve_relink.output for spec
+      $INPUT.SPEC_ID.
+
+      Candidates were:
+      $search_candidates.output
+
+      Call specship_link_assert with the chosen candidate's path and
+      qualified_name (and the original kind, default "implements").
+
+      Output: confirmation of the new link.

package/dist/workflows/defaults/spec-verify.yaml

@@ -0,0 +1,51 @@
+name: spec-verify
+description: Run verification across all 'implemented' spec links. Use as a CI gate or pre-commit check.
+tags: [spec, default, ci]
+requires: [specship, tests]
+
+# No worktree — runs in-place against the current checkout.
+worktree:
+  enabled: false
+
+nodes:
+  - id: run_tests
+    kind: bash
+    output_type: test_results
+    timeout: 600000
+    bash: |
+      if [ -f package.json ]; then
+        npm test
+      elif [ -f Cargo.toml ]; then
+        cargo test
+      elif [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+        python -m pytest
+      else
+        echo "no recognised test framework; skipping" >&2
+        exit 0
+      fi
+
+  - id: summarize
+    kind: prompt
+    depends_on: [run_tests]
+    output_type: link_summary
+    trigger_rule: all_done
+    allowed_tools:
+      - mcp__specship__specship_drifted
+      - mcp__specship__specship_spec
+      - mcp__specship__specship_link_verify
+    prompt: |
+      Test run completed. Output (truncated):
+
+      $run_tests.output
+
+      1. Call specship_drifted to see any drifted/broken/orphaned links.
+      2. If tests passed (no failures reported), iterate over each
+         'implemented' link and call specship_link_verify(result: "pass")
+         to promote them to "verified". (Skip links that are already
+         verified.)
+      3. If tests failed, identify which specs the failing tests are
+         tied to and call specship_link_verify(result: "fail", reason:
+         "<test name>") on those links.
+
+      Output: a short summary of how many links moved to verified,
+      how many to broken, and which specs are still drifted.

package/dist/workflows/discovery.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Workflow discovery — three-tier precedence loader.
+ *
+ * Inspired by Archon's `packages/workflows/src/workflow-discovery.ts:205-361`.
+ *
+ * Precedence (highest wins on filename collision):
+ *   1. Bundled defaults  (compiled-in, see ./defaults/index.ts)
+ *   2. Global   `~/.specship/workflows/`
+ *   3. Project  `<projectRoot>/.specship/workflows/`
+ *
+ * One level of nesting (`subdir/foo.yaml`) is allowed; deeper paths are
+ * silently ignored to keep discovery cheap and predictable. Per-file YAML
+ * parse or validation failures are isolated — one broken workflow does
+ * not abort discovery of its peers.
+ */
+import { WorkflowDefinition, ValidationError } from './schemas/workflow';
+export type WorkflowScope = 'bundled' | 'global' | 'project';
+export interface WorkflowWithSource {
+    workflow: WorkflowDefinition;
+    scope: WorkflowScope;
+    sourcePath: string;
+}
+export interface WorkflowLoadError {
+    scope: WorkflowScope;
+    sourcePath: string;
+    errors: ValidationError[];
+}
+export interface WorkflowLoadResult {
+    /** Discovered workflows, after precedence resolution. */
+    workflows: WorkflowWithSource[];
+    /** Errors per failed workflow file. */
+    errors: WorkflowLoadError[];
+}
+/**
+ * Discover workflows from bundled defaults + global + project scopes.
+ * Project overrides global; global overrides bundled. Matching is by
+ * filename stem (e.g. `spec-implement.yaml` at project level overrides
+ * any `spec-implement.yaml` from bundled).
+ */
+export declare function discoverWorkflows(projectRoot: string): WorkflowLoadResult;
+/**
+ * Load a single workflow by name from the resolved discovery layer.
+ * Returns null if no workflow with that name exists in any scope.
+ */
+export declare function loadWorkflowByName(projectRoot: string, name: string): WorkflowWithSource | null;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/workflows/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/workflows/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,EACL,kBAAkB,EAElB,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAG5B,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,uCAAuC;IACvC,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAoCzE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,kBAAkB,GAAG,IAAI,CAG3B"}