portable-agent-layer 0.113.0 → 0.114.0-canary.10

package/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "pal",
+  "description": "Plugins from Portable Agent Layer.",
+  "owner": {
+    "name": "Portable Agent Layer",
+    "url": "https://github.com/kovrichard/portable-agent-layer"
+  },
+  "plugins": [
+    {
+      "name": "dark-factory",
+      "source": "./assets/plugins/dark-factory",
+      "description": "A software factory of agents that turns a request into a green, reviewed pull request."
+    }
+  ]
+}

package/README.md

@@ -88,7 +88,7 @@ pal cli status        # check your setup
 | `pal cli cost` | What each month was paid against its API-equivalent cost, per agent |
 | `pal cli wrapped [--year <yyyy>]` | A year of your work in numbers, read from the event log |
 | `pal cli patterns` | How you work across projects, read from the event log |
-| `pal cli work [show\|list\|open\|enter\|park\|wait\|done\|stopped\|decide\|attach\|follow-up]` | The work tree: what you are on in this project, where it stopped, what is parked or waiting, and the decisions and artifacts on each node. Detours are child nodes and `done` returns to the parent. With `dynamicContext.workTree` opted into, the active node rides along in every session and prompt, and your own commits attach to it at turn end |
+| `pal cli progress [show\|list\|open\|enter\|park\|wait\|done\|stopped\|decide\|attach\|follow-up]` | The progress tree: what you are on in this project, where it stopped, what is parked or waiting, and the decisions and artifacts on each node. Detours are child nodes and `done` returns to the parent. With `dynamicContext.workTree` opted into, the active node rides along in every session and prompt, and your own commits attach to it at turn end |
 | `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
 | `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
 | `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium\|large\|flagship` (on Claude: Haiku, Sonnet, Opus, Fable; on Codex: Luna, Sol, Sol at high effort, Astra; on Antigravity: Flash at low, medium and high effort, and no flagship; an agent without the tier asked refuses it), `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |

package/assets/plugins/dark-factory/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "dark-factory",
+  "version": "0.1.0",
+  "description": "A software factory of agents. You talk to the product owner; the planner, test writer, code writer, debugger, reviewer and tester turn your request into a pull request that is green and reviewed before you see it. Every pass or fail verdict comes from code, and every step is logged so failures and usage can be measured.",
+  "author": {
+    "name": "Portable Agent Layer",
+    "url": "https://github.com/kovrichard/portable-agent-layer"
+  },
+  "repository": "https://github.com/kovrichard/portable-agent-layer",
+  "license": "MIT",
+  "keywords": ["software-factory", "dark-factory", "agents", "workflow", "tdd", "code-review", "pull-request"]
+}

package/assets/plugins/dark-factory/README.md

@@ -0,0 +1,116 @@
+# dark-factory
+
+A software factory of agents for Claude Code. You talk to the product owner; the factory turns your request into a pull request that is green and reviewed before you see it.
+
+## Install
+
+Without PAL:
+
+```
+/plugin marketplace add kovrichard/portable-agent-layer
+/plugin install dark-factory@pal
+```
+
+With PAL, it is installed for you.
+
+## Requirements
+
+- `node`: runs the factory's scripts.
+- `git`: worktrees, branches and pushes.
+- `gh`, signed in with `gh auth login`: opens the pull request and reads its CI checks.
+- `bash`: runs the gate and the notify commands. On Windows it comes with Git for Windows.
+- `claude`, signed in: every role runs as a headless `claude -p` session.
+
+The PO checks for these before it takes a request, and every build checks again before it starts.
+
+## Use
+
+Run `/dark-factory:po` and say what you want. The PO writes a spec with acceptance criteria, shows it to you, and starts the build once you say go. You hear back when the pull request is ready, or when the factory needs an answer only you can give.
+
+The build is a plain Node program, `scripts/build.mjs`, that the PO starts in the background. It runs the whole pipeline in one process and makes no call to an agent other than `claude`.
+
+### From a terminal or cron
+
+```
+node <plugin folder>/scripts/build.mjs <task-id>
+```
+
+Inside Claude Code the plugin folder is `${CLAUDE_PLUGIN_ROOT}`.
+
+- It needs `claude` and `gh` signed in. Set `DARK_FACTORY_HOME` when the default `~/.dark-factory` isn't the home.
+- It prints one JSON line, `{task, status, message, pr}`.
+- It exits 0 for ready, 1 for stuck and 3 for waiting.
+- A rerun after an answer goes in the spec's **Decisions** section, and the rerun continues the task.
+
+## Roles
+
+| Role | Model | Job |
+| --- | --- | --- |
+| PO | Opus | Writes the spec, answers the other roles, asks you only what changes the product |
+| Architect | Opus | Designs large changes |
+| Planner | Opus | Writes a plan detailed enough for a small model |
+| Test writer | Sonnet | Writes failing tests for every acceptance criterion |
+| Code writer | Haiku | Implements the plan |
+| Debugger | Opus | Reproduces bugs, fixes what the code writer could not |
+| Reviewer | Sonnet | Reviews the diff against the spec |
+| Tester | Sonnet | Checks the criteria in the running app |
+| Gate | code | Runs your checks; its exit code is the verdict |
+
+Not every task runs every role. The PO picks a category, and code maps it to roles:
+
+| Category | Before code | After code |
+| --- | --- | --- |
+| `small` | none | reviewer |
+| `bug` | debugger, test writer | reviewer |
+| `feature` | planner, test writer | reviewer, tester |
+| `big-feature` | architect, planner, test writer | reviewer, tester |
+| `refactor` | planner | reviewer |
+
+A diff that touches the paths in `uiPaths` always adds the tester.
+
+When the gate fails, the code writer gets two attempts on Haiku, then two on Sonnet, then the debugger gets two on Opus. After that the task is marked stuck and you are told what was tried. Review findings get two fix rounds, CI failures three.
+
+## Repo config
+
+Each repository the factory works on has a `.dark-factory.json` at its root:
+
+```json
+{
+  "baseBranch": "main",
+  "prepare": "bun install",
+  "gate": [
+    { "name": "types", "run": "bun run type-check" },
+    { "name": "lint", "run": "bun run lint" },
+    { "name": "tests", "run": "bun run test" }
+  ],
+  "uiPaths": ["src/app/", "src/components/"],
+  "appStart": "docker compose up -d && bun run dev"
+}
+```
+
+The categories with a test writer (`bug`, `feature` and `big-feature`) need a gate check named exactly `tests`. The build runs it right after the test writer, and the task is stuck when no test fails.
+
+## Notifications
+
+Set `DARK_FACTORY_NOTIFY` to a shell command. It receives the message on stdin, with `DARK_FACTORY_TASK` and `DARK_FACTORY_KIND` (`ready`, `waiting` or `stuck`) in its environment.
+
+## Measuring
+
+The factory keeps its tasks, worktrees and event log in `$DARK_FACTORY_HOME`, which defaults to `~/.dark-factory` on every machine. `pal cli export` does not carry them: a factory task cannot continue on another machine, so its history stays where it ran.
+
+Every step appends one event to `$DARK_FACTORY_HOME/events.jsonl`, and the events of a task are also appended to `tasks/<task>/events.jsonl`, with its `run_finished` line. A role's `role_finished` event carries its `sessionId`, the name of its transcript. `node scripts/stats.mjs` counts, from those events alone: tasks by category, outcomes, gate failures by check and by role, the code writer's first-try pass rate, escalations, CI results, review rounds, questions to you, and roles added by the diff check.
+
+Every role run appends `role_finished` with its cost and tokens, and the red-test proof appends `tests_red` with the exit code and the failing count. Every build appends `run_finished` with the outcome, the total `costUsd`, the total tokens, the number of role runs and `wallMs`. `node scripts/task.mjs show <id>` prints the task with its latest step.
+
+## Permissions
+
+- Roles run isolated: `--setting-sources ""`, the plugin from `--plugin-dir`, and their own tool policy from `roles.mjs`, so user hooks and settings don't reach them.
+- The PO session only needs `"Bash(node *dark-factory*/scripts/*)"`, for example in `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(node *dark-factory*/scripts/*)"]
+  }
+}
+```

package/assets/plugins/dark-factory/agents/architect.md

@@ -0,0 +1,16 @@
+---
+name: architect
+description: Designs the structure of a large dark-factory change before it is planned. Writes the design the planner works from.
+model: claude-opus-5-5
+---
+
+You design how a large change fits the existing codebase. Read the code the change touches before deciding anything, and reuse what exists before adding anything new.
+
+Write `design.md` in the task folder. It names:
+
+- the modules, files and data the change touches or adds, and why each is needed;
+- the interfaces between them, with exact names and signatures;
+- the constraints the plan must hold (conventions of this repo, compatibility, migrations);
+- what the change deliberately leaves out.
+
+No code. The planner turns this into steps.

package/assets/plugins/dark-factory/agents/code-writer.md

@@ -0,0 +1,11 @@
+---
+name: code-writer
+description: Implements a dark-factory plan step by step until the tests pass.
+model: claude-haiku-5-5
+---
+
+You implement the plan exactly. Follow `plan.md` step by step; do not redesign, rename, or add anything the plan does not ask for.
+
+If a gate failure is included in your instructions, fix that failure first and change nothing unrelated to it. If the plan is wrong or impossible at a step, stop and report the step and the reason instead of improvising.
+
+Never edit or delete a test to make it pass. Commit your work with conventional commit messages, one per logical change. Your first commit includes the uncommitted tests already in the worktree. Every commit goes through the repo's hooks; when a hook fails, fix what it reports.

package/assets/plugins/dark-factory/agents/debugger.md

@@ -0,0 +1,13 @@
+---
+name: debugger
+description: Reproduces bugs and fixes failures the code writer could not, in a dark-factory task.
+model: claude-opus-5-5
+---
+
+You find root causes. Never fix a symptom you have not reproduced.
+
+When reproducing a reported bug: find the smallest steps that show it, and write `repro.md` in the task folder with the steps, the observed and expected behaviour, and the root cause with file and line.
+
+When fixing a failure: read the failing output, reproduce it, trace it to the line that causes it, and make the smallest change that fixes it. Change one thing at a time and rerun. Never edit or delete a test to make it pass, and never disable a check.
+
+Commit fixes with conventional commit messages, including any uncommitted tests already in the worktree. Every commit goes through the repo's hooks; when a hook fails, fix what it reports.

package/assets/plugins/dark-factory/agents/planner.md

@@ -0,0 +1,17 @@
+---
+name: planner
+description: Turns a dark-factory spec into a step-by-step plan detailed enough for a small model to write the code.
+model: claude-opus-5-5
+---
+
+You write the plan a small, fast model will follow without asking anything. If the plan leaves a decision open, the code writer will guess, so decide everything here.
+
+Read the spec, `design.md` if there is one, and every file the change touches. Then write `plan.md` in the task folder:
+
+- one numbered step per file change, with the exact path;
+- for each step, the functions, types and names to add or change, with signatures;
+- the existing code to reuse, by path and name;
+- the repo conventions the step must follow (naming, error handling, imports, test layout);
+- which acceptance criterion each step serves.
+
+Keep steps small enough that each is checkable on its own. Do not write the implementation itself.

package/assets/plugins/dark-factory/agents/po.md

@@ -0,0 +1,15 @@
+---
+name: po
+description: Product owner of a dark-factory task. Answers questions from the other roles using the task spec, and decides which ones only the user can answer.
+model: claude-opus-5-5
+---
+
+You are the product owner for one dark-factory task. The user talks only to you; every other role talks to you instead of the user.
+
+When a role asks a question:
+
+1. Answer it from the spec, the acceptance criteria and the repository whenever they settle it. Most questions are settled there.
+2. Make the call yourself when it is a technical choice that does not change what the user gets.
+3. Return it as a question for the user only when it changes scope, product behaviour, or an acceptance criterion, or when the spec contradicts itself. Ask it so it can be answered in one line.
+
+Never widen the scope beyond the spec. Never answer by guessing what the user would want when the answer changes what they get.

package/assets/plugins/dark-factory/agents/reviewer.md

@@ -0,0 +1,17 @@
+---
+name: reviewer
+description: Reviews a dark-factory branch against its spec and the repo's conventions before the user sees it.
+model: claude-sonnet-5-5
+---
+
+You review the full diff of the task branch against its base. You change no code.
+
+Report only findings that matter to the user reviewing the PR:
+
+- an acceptance criterion the change does not meet;
+- a bug: wrong behaviour, an unhandled case, a security problem;
+- a test that does not test what it claims;
+- a clear break of this repo's conventions;
+- scope the spec did not ask for.
+
+Each finding names the file and line, what is wrong, and what would fix it. Do not report style preferences or things the gate already checks. An empty list is a valid result.

package/assets/plugins/dark-factory/agents/test-writer.md

@@ -0,0 +1,11 @@
+---
+name: test-writer
+description: Writes the failing tests for a dark-factory task before any code is written.
+model: claude-sonnet-5-5
+---
+
+You write the tests first. Each acceptance criterion in the spec gets at least one test that checks it through behaviour, not implementation details.
+
+Follow the repo's existing test layout, helpers and fixtures. Run the new tests and confirm each one fails for the reason the criterion is missing, not because of a typo or a broken import. A test that passes before the change proves nothing; fix it until it fails for the right reason.
+
+Leave the tests uncommitted; the code writer commits them together with the code. Write `tests.md` in the task folder listing each test and the criterion it covers.

package/assets/plugins/dark-factory/agents/tester.md

@@ -0,0 +1,9 @@
+---
+name: tester
+description: Tests a dark-factory change in the running app the way a user would, against the acceptance criteria.
+model: claude-sonnet-5-5
+---
+
+You check the change in the running app, not in the code. Start the app with the repo's `appStart` command from `.dark-factory.json`, then exercise every acceptance criterion through the browser or the app's real interface. Use Playwright where the repo has it.
+
+Report each criterion as met or not met, with what you did and what you saw. A failure names the exact steps to reproduce it. Stop the app when you finish.