nightralph 0.0.0

package/scripts/clone-skills.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO="https://github.com/mattpocock/skills.git"
+SKILLS_DIR="./src/skills"
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+git clone --depth 1 --quiet "$REPO" "$TMP_DIR"
+COMMIT=$(git -C "$TMP_DIR" rev-parse --short HEAD)
+
+copy_skill () {
+    local upstream_path="$1"
+    local local_name="$2"
+    local src="$TMP_DIR/$upstream_path"
+    local dest="$SKILLS_DIR/$local_name"
+
+    rm -rf "$dest"
+    mkdir -p "$dest"
+
+    find "$src" -maxdepth 1 -type f -exec cp {} "$dest/" \;
+
+    if [ -d "$src/agents" ]; then
+        cp -r "$src/agents" "$dest/"
+    fi
+
+    echo "  $local_name/ <- $upstream_path"
+}
+
+echo "Cloning skills from mattpocock/skills..."
+
+copy_skill "skills/engineering/grill-with-docs" "grill"
+copy_skill "skills/productivity/grilling" "grilling"
+copy_skill "skills/engineering/domain-modeling" "domain-modeling"
+copy_skill "skills/engineering/to-spec" "to-spec"
+copy_skill "skills/engineering/to-tickets" "to-tickets"
+copy_skill "skills/engineering/tdd" "tdd"
+
+# grill-with-docs is exposed as /grill
+sed -i '' 's/^name: grill-with-docs$/name: grill/' \
+    "$SKILLS_DIR/grill/SKILL.md"
+
+cat > "$SKILLS_DIR/upstream.json" <<EOF
+{
+  "repo": "mattpocock/skills",
+  "commit": "$COMMIT",
+  "pulledAt": "$(date +%Y-%m-%d)"
+}
+EOF
+
+echo ""
+echo "Done. Commit: $COMMIT"

package/specs/prd.json

@@ -0,0 +1,172 @@
+{
+  "project": "nightralph",
+  "branchName": "ralph/integration-test-coverage",
+  "description": "Integration tests for the CLI layer, validating subprocess execution, argument forwarding, dry-run output, edge cases, and setup-to-execute composition",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Unit tests for findFeatureDirs",
+      "description": "As a developer, I want direct tests for findFeatureDirs so that feature directory discovery is validated independently.",
+      "acceptanceCriteria": [
+        "Create test/integration.test.ts with findFeatureDirs tests",
+        "Test: returns empty array when .scratch/ does not exist",
+        "Test: returns empty array when .scratch/ has directories without issues/ subdirs",
+        "Test: returns entries with correct name, dir, and spec paths for valid feature dirs",
+        "Test: ignores non-directory entries in .scratch/",
+        "Each test creates and cleans up its own temp directory",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 1,
+      "passes": true,
+      "notes": "findFeatureDirs is already exported from src/index.ts -- import it directly"
+    },
+    {
+      "id": "US-002",
+      "title": "Unit tests for resolveIssuesDir with explicit flags",
+      "description": "As a developer, I want to verify that when both --dir and --spec are provided, resolveIssuesDir returns them directly without scanning .scratch/.",
+      "acceptanceCriteria": [
+        "Add resolveIssuesDir tests to test/integration.test.ts",
+        "Test: returns { dir, spec } exactly as given when both flags are provided",
+        "No filesystem scanning occurs (the temp dir has no .scratch/)",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 2,
+      "passes": true,
+      "notes": "resolveIssuesDir is already exported from src/index.ts"
+    },
+    {
+      "id": "US-003",
+      "title": "Subprocess CLI smoke test for execute",
+      "description": "As a developer, I want a test that spawns node dist/index.js <provider> as a child process so that I know the yargs wiring, argument parsing, and file resolution work end-to-end.",
+      "acceptanceCriteria": [
+        "Test spawns the built CLI with --dir, --spec, and --timeout-secs pointing at a temp directory with ticket files",
+        "Uses the existing mock-agent-pass.js as the provider argument",
+        "Asserts exit code 0",
+        "Asserts ticket files on disk are updated to **Status:** done",
+        "Asserts log files are created in the expected location",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 3,
+      "passes": true,
+      "notes": "Use short --timeout-secs (e.g. 10) to avoid hanging"
+    },
+    {
+      "id": "US-004",
+      "title": "Create mock-agent-echo-args and test --model flag",
+      "description": "As a developer, I want to verify that --model (or -m) is passed through to the spawned agent process so that running npx nightralph claude -m claude-sonnet-4-6 actually forwards the model argument.",
+      "acceptanceCriteria": [
+        "Create test/mock-agent-echo-args.js that writes process.argv to stdout, then exits 0",
+        "Test spawns the CLI with -m test-model using this mock agent",
+        "Asserts the log file contains --model and test-model in the captured argv",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 4,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-005",
+      "title": "Subprocess CLI test for --dry-run",
+      "description": "As a developer, I want a test that runs the CLI with --dry-run so that I know the dry-run path works through yargs and produces the expected output.",
+      "acceptanceCriteria": [
+        "Test spawns the built CLI with --dry-run, --dir, and --spec",
+        "Captures stdout",
+        "Asserts output contains Wave 1: with the expected ticket filenames",
+        "Asserts output contains AGENT INSTRUCTIONS (prompt preview)",
+        "Asserts ticket files on disk are NOT modified",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 5,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-006",
+      "title": "CLI exits gracefully when no tickets found",
+      "description": "As a developer, I want to verify the CLI handles the empty-directory edge case gracefully.",
+      "acceptanceCriteria": [
+        "Test points --dir at an empty directory with a valid --spec",
+        "Asserts stdout contains No ticket files found",
+        "Asserts exit code 0 (graceful, not a crash)",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 6,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-007",
+      "title": "CLI exits with error for missing dir/spec",
+      "description": "As a developer, I want the CLI to fail clearly when --dir or --spec point to nonexistent paths.",
+      "acceptanceCriteria": [
+        "Test passes --dir /nonexistent/path with a valid --spec",
+        "Asserts exit code is non-zero",
+        "Asserts stderr contains not found",
+        "Test passes valid --dir with --spec /nonexistent/spec.md",
+        "Asserts exit code is non-zero",
+        "Asserts stderr contains not found",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 7,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-008",
+      "title": "Unknown blocker warning and stripping",
+      "description": "As a developer, I want to verify that runExecute warns about blockers referencing nonexistent ticket numbers and strips them so execution proceeds.",
+      "acceptanceCriteria": [
+        "Test creates a ticket with **Blocked by:** 99 where ticket 99 does not exist",
+        "Spawns the CLI as a subprocess",
+        "Asserts stderr/stdout contains a warning mentioning blocker 99",
+        "Asserts the ticket still completes (blocker was stripped)",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 8,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-009",
+      "title": "Dry-run deadlock detection",
+      "description": "As a developer, I want the dry-run to report deadlocked tickets (circular dependencies) so users can fix their ticket graph before running real agents.",
+      "acceptanceCriteria": [
+        "Test creates two tickets that block each other (1 blocks 2, 2 blocks 1)",
+        "Spawns the CLI with --dry-run",
+        "Asserts output contains Deadlocked tickets with both filenames",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 9,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-010",
+      "title": "Setup-then-execute composition test",
+      "description": "As a developer, I want a test that runs setup, then creates issue files in the expected .scratch/ layout, then runs execute -- proving the two commands compose correctly.",
+      "acceptanceCriteria": [
+        "Test calls setup() with tracker:'local' in a temp project dir",
+        "Creates .scratch/<feature>/issues/ with 2 ticket files and a spec.md",
+        "Spawns the CLI as a subprocess pointing at that project dir (using the mock agent)",
+        "Asserts tickets are marked done",
+        "Asserts logs are written to .scratch/<feature>/logs/",
+        "Asserts docs/agents/issue-tracker.md exists (from setup)",
+        "Asserts .agents/skills/ directories exist (from setup)",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 10,
+      "passes": true,
+      "notes": "Most complex test -- calls setup() as a library function, then spawns CLI for execute"
+    }
+  ]
+}

package/src/docs-templates/domain.md

@@ -0,0 +1,36 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because..._

package/src/docs-templates/issue-tracker-github.md

@@ -0,0 +1,228 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub Issues, managed via the `gh` CLI.
+
+## Conventions
+
+- One feature per GitHub issue milestone (optional, for grouping)
+- Specs are tracked as issues with label `spec`
+- Implementation issues are tracked as GitHub issues, one per task
+- Triage state is recorded via issue labels (see `triage-labels.md` for the role strings)
+- Comments and conversation history are on the GitHub issue thread
+- Use task lists in issue bodies for sub-tasks that don't warrant separate issues
+
+## Prerequisites
+
+Install the `gh` CLI: https://cli.github.com
+
+Authenticate with your GitHub account:
+
+```bash
+gh auth login
+```
+
+Verify authentication:
+
+```bash
+gh auth status
+```
+
+## Basic Operations
+
+### Create an issue (publish to tracker)
+
+```bash
+gh issue create --title "Issue title" --body "Issue description"
+```
+
+For an issue with labels:
+
+```bash
+gh issue create --title "Fix login bug" --body "Users see 404 on login page" --label "bug,p0"
+```
+
+### View an issue (fetch the relevant ticket)
+
+```bash
+gh issue view <number>
+```
+
+Example:
+
+```bash
+gh issue view 42
+```
+
+### List issues
+
+Show all open issues:
+
+```bash
+gh issue list
+```
+
+Show issues with a specific label:
+
+```bash
+gh issue list --label "bug"
+```
+
+Show issues assigned to you:
+
+```bash
+gh issue list --assignee "@me"
+```
+
+### Add a comment
+
+```bash
+gh issue comment <number> --body "Comment text"
+```
+
+### Close an issue
+
+```bash
+gh issue close <number>
+```
+
+To close with a comment:
+
+```bash
+gh issue close <number> --comment "Resolved in PR #99"
+```
+
+### Reopen an issue
+
+```bash
+gh issue reopen <number>
+```
+
+## Label Management
+
+### Apply labels
+
+Add a label to an existing issue:
+
+```bash
+gh issue edit <number> --add-label "in-progress"
+```
+
+### Remove labels
+
+Remove a label from an issue:
+
+```bash
+gh issue edit <number> --remove-label "blocked"
+```
+
+### View available labels
+
+```bash
+gh label list
+```
+
+## When a skill says "publish to the issue tracker"
+
+Create a new GitHub issue:
+
+```bash
+gh issue create --title "..." --body "..." --label "..."
+```
+
+Then note the issue number for reference.
+
+## When a skill says "fetch the relevant ticket"
+
+View the issue:
+
+```bash
+gh issue view <number>
+```
+
+The user will normally pass the issue number.
+
+## Wayfinding Operations
+
+Used by `/wayfinder` and similar domain-driven agents. GitHub Issues uses native features for navigation:
+
+- **Map**: A pinned issue or GitHub project that lists related issues as task items
+- **Child issues**: Related issues linked via GitHub issue dependencies (see below)
+- **Blocking**: Use GitHub issue dependencies to mark blocking relationships
+- **Frontier**: Query with `gh issue list --state open --assignee "" --label "available"`
+- **Claim**: Assign the issue to yourself with `gh issue edit <number> --add-assignee "@me"`
+- **Resolve**: Close the issue and link to context (PR, gist, decision record) in the final comment
+
+## Blocking and Dependencies
+
+### Mark as blocked
+
+Add the `blocked` label and optionally a comment referencing the blocking issue:
+
+```bash
+gh issue edit <number> --add-label "blocked"
+gh issue comment <number> --body "Blocked by #42"
+```
+
+### Link related issues
+
+Use issue references in comments and body text. GitHub auto-links:
+
+```bash
+# In an issue comment or body, write:
+Relates to #123
+Depends on #456
+Blocks #789
+Fixed in #999
+```
+
+These create bidirectional links visible in the issue UI.
+
+### Check if unblocked
+
+Query the blocking issues referenced in the issue's comments or description. An issue is unblocked when no blocking issues remain open.
+
+## Frontier Query and Workflow
+
+### Find available issues
+
+Query for open, unassigned issues:
+
+```bash
+gh issue list --state open --assignee "" --label "available,p0" --json number,title
+```
+
+### Claim an issue
+
+Assign to yourself when starting work:
+
+```bash
+gh issue edit <number> --add-assignee "@me"
+```
+
+Optionally add `in-progress` label:
+
+```bash
+gh issue edit <number> --add-label "in-progress"
+```
+
+### Resolve an issue
+
+Work through the issue in a PR. When done, close the issue and link the PR:
+
+```bash
+gh issue close <number> --comment "Resolved in PR #999"
+```
+
+Alternatively, create a closing comment with a reference:
+
+```bash
+gh issue comment <number> --body "Fixed in PR #999"
+gh issue close <number>
+```
+
+## Tips
+
+- Use GitHub milestones to group related features
+- Use `gh issue create --web` to open the issue creation form in your browser
+- Use `gh issue edit <number> --web` to open an issue in the browser for complex edits
+- Save frequently-used queries as saved views in the GitHub web UI

package/src/docs-templates/issue-tracker.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`, never a single combined tickets file
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` (the Notes / Decisions-so-far / Fog body).
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/src/docs-templates/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.