nightralph 0.0.0

package/.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "mattpocock-skills@claude-plugins-official": true
+  }
+}

package/AGENTS.md

@@ -0,0 +1,60 @@
+# nightralph
+
+Last verified: 2026-08-27
+
+Small orchestrator that runs a single-agent session per issue.
+
+## Tech Stack
+- TypeScript, Node >= 18, ESM
+- CLI: yargs + @inquirer/prompts
+- Testing: @substrate-system/tapzero
+
+## Commands
+- `npm run build` -- build to dist/
+- `npm test` -- build and run tests
+- `npm run lint` -- eslint
+
+## Project Structure
+- `src/index.ts` -- CLI entry point (yargs commands)
+- `src/setup.ts` -- project scaffolding module
+- `src/orchestrator.ts` -- ticket scanning and wave execution
+- `src/skills/` -- bundled skill definitions
+- `src/docs-templates/` -- doc templates copied to target projects
+
+## Contracts
+
+### setup module (`src/setup.ts`)
+- **Exposes**: `setup(opts)`, `checkGhAuth()`,
+  `TrackerKind`, `SetupOpts`, `SKILL_DIRS`, `DOC_TEMPLATES`
+- **TrackerKind**: `'github'|'local'`
+- **SetupOpts.tracker**: required -- selects which
+  issue-tracker template is installed and what AGENTS.md
+  content is generated in the target project
+- **checkGhAuth()**: returns true when
+  `gh auth status` succeeds
+- **DOC_TEMPLATES**: `['triage-labels.md', 'domain.md']` --
+  issue-tracker.md is handled separately via tracker selection
+- **Guarantees**: `setup()` always overwrites
+  `issue-tracker.md` (not skip-if-exists like other
+  templates); always writes AGENTS.md to the target project
+
+### CLI (`src/index.ts`)
+- `nightralph setup [--claude]` -- prompts for tracker
+  format, then scaffolds skills and docs
+- `nightralph <provider> [options]` -- executes tickets
+
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked as local markdown files under
+`.scratch/`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default label vocabulary.
+See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout. See `docs/agents/domain.md`.

package/CLAUDE.md

@@ -0,0 +1 @@
+Read @./AGENTS.md and treat its contents as if they were in CLAUDE.md

package/PROMPT.md

@@ -0,0 +1,95 @@
+# MISSION
+
+Build and maintain nightralph -- a small orchestrator CLI that runs
+single-agent sessions per issue.
+
+# Role
+You are an expert TypeScript/Node.js engineer specializing in CLI tools,
+process orchestration, and test automation.
+
+# Objective
+
+Develop and test a CLI orchestrator using:
+
+- Runtime: Node >= 18, ESM
+- CLI: yargs for command parsing, @inquirer/prompts for interactive input
+- Build: esbuild (ESM output to dist/)
+- Testing: @substrate-system/tapzero
+
+## META INSTRUCTION
+
+Before performing any tool call or code change, emit a short, one-line status
+update in the terminal starting with 'LOG: [Action]'. This helps me track your
+progress in the Ralph Loop.
+
+## EXECUTION RULES
+
+1. READ: At the start of EVERY session, read `specs/prd.json` and `progress.log`.
+2. SCOPE: Pick the highest-priority task where `passes: false` (or missing).
+   Work ONLY on that one task. Do not touch or mark any other story.
+3. WRITE TESTS FIRST: Write failing tests for the feature/bug, then implement
+   until they pass.
+4. TARGETED TESTING WHILE WORKING:
+   - DO NOT run the full suite (`npm test`) for every minor change.
+   - DO run only the tests relevant to the file you are editing
+     (e.g., `npx vitest run path/to/file.spec.ts`).
+5. VERIFY BEFORE COMMIT (and only then run the full suite):
+   - Run `npm run lint`.
+   - Run the FULL suite `npm test` ONCE, when you believe the task is complete.
+   - If lint or the full suite fails, fix it before committing.
+   (Rules 4 and 5 are complementary: targeted tests during the work, one full
+    suite run as the final gate. Never run the full suite after every edit.)
+6. DOCUMENT: Append to `progress.log` what changed and any new patterns or
+   gotchas discovered (these become context for future sessions).
+7. UPDATE PRD: In `specs/prd.json`, set `passes: true` for the completed story
+   ONLY. Leave every other story untouched.
+8. COMMIT: After the full suite passes, commit with a descriptive message like
+   `FEATURE: [TaskID] - [Description]`. ALWAYS COMMIT AFTER COMPLETING A TASK —
+   an uncommitted change does not count as progress.
+9. ATOMICITY: Complete EXACTLY ONE task per session, then STOP.
+
+## CRITICAL: NON-INTERACTIVE MODE
+
+This is an autonomous session. You must NEVER:
+- Ask clarifying questions.
+- Wait for user input.
+- Output questions like 'What would you like me to work on?'
+If a detail is genuinely ambiguous, make the most reasonable assumption,
+record it in `progress.log`, and proceed.
+
+## Strict Constraints
+
+- Do NOT add new dependencies. If you believe one is truly required, do not
+  install it -- document the need in `progress.log` and proceed without it.
+- Prefer standard Node.js APIs over third-party alternatives wherever possible.
+- Stay within the tech stack above. Do not introduce other test runners or
+  build tools.
+
+# Technical Constraints
+
+- CLI entry point: `src/index.ts` (yargs commands)
+- Project scaffolding: `src/setup.ts`
+- Ticket scanning and wave execution: `src/orchestrator.ts`
+- Bundled skills: `src/skills/`
+- Doc templates: `src/docs-templates/`
+- Build: `npm run build` (esbuild to dist/)
+- Test: `npm test` (esbuild + node to run tapzero tests)
+- Lint: `npm run lint` (eslint)
+
+# Error Handling
+
+If you hit a bug you cannot fix this session, document the failure and what you
+tried in `progress.log`, then stop. Do not loop on the same failing approach --
+a future session (with stronger reasoning hints) will pick it up.
+
+## STOP CONDITION
+
+Once ALL tasks in `specs/prd.json` have `passes: true`, output the EXACT string
+on its own line, as your final message, after the work is verified:
+
+<promise>COMPLETE</promise>
+
+Do not emit that string in any other context (e.g., while planning or
+explaining) -- the loop treats it as a completion signal only when the PRD also
+shows zero pending tasks, so emitting it early just wastes a check. Do not
+perform any further work once all tasks are verified.

package/README.md

@@ -0,0 +1,138 @@
+# `nightralph`
+
+This is a minimal Node-based AI orchestrator. It reads local markdown tickets
+produced by
+[`to-tickets` skill](https://github.com/mattpocock/skills/blob/main/skills/engineering/to-tickets/SKILL.md),
+resolves their dependency graph, and runs agents in parallel as much as possible,
+honoring the ticket dependencies.
+
+This is inspired by [nightshift](https://github.com/Shaurya-Sethi/nightshift/).
+I made it because I noticed that the API in `nightshift` had already drifted
+from the skill definitions. This module bundles its skill dependencies,
+so they can't drift as long as you install the skills with this package.
+(See [the section on the `setup` command](#install-dependency-skills).)
+
+<!-- toc -->
+
+- [Install](#install)
+  * [Install Dependency Skills](#install-dependency-skills)
+  * [Create Issues](#create-issues)
+  * [Execute Issues](#execute-issues)
+- [Workflow](#workflow)
+  * [`nightralph` command](#nightralph-command)
+
+<!-- tocstop -->
+
+## Install
+
+```bash
+npm i -S nightralph
+```
+
+### Install Dependency Skills
+
+Use a subcommand in this package to add the required
+[Pocock skills](https://github.com/mattpocock/skills) to your repo.
+This command will copy some files in this package to a specific directory
+in the consumer's repo. The upstream
+[`grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md)
+skill is exposed as `/grill`, along with its sub-skills
+`grilling` and `domain-modeling`.
+
+```sh
+npx nightralph setup
+```
+
+The Pocock skills are bundled with this git repo, at `./skills`.
+They are cloned with some metadata, visible in
+[skill/upstream.json](skills/upstream.json).
+That's how we prevent skill vs API drift.
+
+
+### Create Issues
+
+First create issues.
+
+This package bundles the skill files with the CLI, to
+**prevent version drift**. After installing this package,
+there is an `npx` command that will add the required skills to your
+local `./claude/skills/` folder.
+
+**The expected flow is**
+
+```
+grill -> to-spec -> to-tickets -> tdd
+```
+
+`to-tickets` will create issues in local markdown files.
+
+### Execute Issues
+
+`to-tickets` produces markdown files at
+`.scratch/<feature>/issues/<NN>-<slug>.md`.
+
+```bash
+# Auto-discover .scratch features and run with claude
+npx nightralph claude -m claude-opus-4-6
+
+# Dry run to inspect the dependency graph and prompt
+npx nightralph claude --dry-run
+
+# Explicit paths (skips auto-discovery)
+npx nightralph claude -m claude-opus-4-6 \
+  --dir .scratch/my-feature/issues \
+  --spec .scratch/my-feature/spec.md
+```
+
+Flags:
+
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `<provider>` | yes | -- | Agent CLI to spawn (e.g. `claude`, `codex`) |
+| `-m`, `--model` | no | -- | Model flag passed to the agent |
+| `--dir` | no | auto | Path to the issues directory |
+| `--spec` | no | auto | Path to the spec file |
+| `--dry-run` | no | -- | Show wave order and prompt without running |
+| `--timeout-secs` | no | `300` | Kill agent after N seconds |
+
+Notes:
+
+* When `--dir` and `--spec` are omitted, the CLI looks for
+  `.scratch/<feature>/issues/` directories. If multiple features exist,
+  **it prompts you to pick one** with an interactive selector.
+* Tickets are selected by `**Status:** ready-for-agent` in the file body.
+* Dependencies are read from the `**Blocked by:**` field; the orchestrator
+  skips tickets whose blockers haven't completed.
+* Unblocked tickets run in parallel. After a wave finishes, newly unblocked
+  tickets start in the next wave.
+* On success (agent exit 0), the ticket's status is updated to `done`
+  in-place. Failed tickets keep their status and block dependents.
+* Agent logs are written to `<dir>/../logs/<ticket>.log`.
+
+
+## Workflow
+
+Need to use several skills, in order:
+
+```
+grill -> to-spec -> to-tickets
+```
+
+At that point you will have a number of tickets, which are markdown files
+in your local repo. This tool handles the last step, implementing the tickets,
+which normally is done with the `tdd` skill. This tool will work in a loop,
+aiming to complete 1 task per session, then restarting (a classic Ralph loop).
+
+### `nightralph` command
+
+After you have the tickets, you can use the `nightralph` loop to execute.
+
+```sh
+npx nightralph claude -m claude-opus-4-6
+```
+
+Or with a different provider:
+
+```sh
+npx nightralph codex -m gpt-5.6-terra
+```

package/WIP.md

@@ -0,0 +1,5 @@
+# WIP
+
+``sh
+/ed3d-plan-and-execute:execute-implementation-plan /Users/nick/code/nightralph/docs/implementation-plans/2026-08-27-issue-tracker-choice/ /Users/nick/code/nightralph/
+```

package/dist/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/dist/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/dist/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/dist/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.