Skip to content

nanaagyei/noetherkin / skills/task-assignment

task-assignment

Verified

Define a bounded, testable Noetherkin assignment and its investigation prompt without revealing the solution. Use when a learner requests next work or a manager recommends new scope; execution gates belong to team-lead.

FileKindSize
SKILL.mdskill md3.7 KB
assets/proposal.mdmarkdown2.0 KB
references/FOUNDATION_V1.mdmarkdown5.4 KB
references/OPEN_QUESTIONS.mdmarkdown3.5 KB
references/PROJECT_CHARTER.mdmarkdown6.4 KB
references/apprenticeship-config.schema.jsonconfig3.0 KB
references/architectural-invariants.mdmarkdown2.3 KB
references/assessment.schema.jsonconfig5.0 KB
references/assistance-model.mdmarkdown4.0 KB
references/attention-advisory.schema.jsonconfig3.8 KB
references/bundle.jsonconfig12.0 KB
references/cli.mdmarkdown18.6 KB
references/competencies.yamlconfig37.7 KB
references/competency-model.mdmarkdown5.0 KB
references/competency-state.schema.jsonconfig3.4 KB
references/conformance.mdmarkdown22.0 KB
references/contract-README.mdmarkdown6.9 KB
references/contract-manager.mdmarkdown2.4 KB
references/contract-task-assignment.mdmarkdown3.2 KB
references/contract-team-lead.mdmarkdown2.8 KB
references/current-project.schema.jsonconfig2.3 KB
references/current-track.schema.jsonconfig1.5 KB
references/evidence-model.mdmarkdown4.1 KB
references/evidence.schema.jsonconfig10.3 KB
references/forge.schema.jsonconfig9.5 KB
references/index.mdmarkdown3.6 KB
references/judgment-validity.mdmarkdown6.6 KB
references/learner-profile.schema.jsonconfig1.5 KB
references/leveling-framework.mdmarkdown3.4 KB
references/levels.yamlconfig8.0 KB
references/overview.mdmarkdown2.9 KB
references/permissions-model.mdmarkdown6.7 KB
references/project.schema.jsonconfig9.4 KB
references/proposals.mdmarkdown4.2 KB
references/review-model.mdmarkdown7.2 KB
references/review.schema.jsonconfig13.0 KB
references/runtime.mdmarkdown7.8 KB
references/selection-model.mdmarkdown6.1 KB
references/simulation-lifecycle.mdmarkdown8.0 KB
references/state-model.mdmarkdown13.7 KB
references/task.schema.jsonconfig13.8 KB
references/track.schema.jsonconfig1.3 KB

references/cli.md

View on GitHub
# Protocol 3.0 CLI

The executable requires Node.js 24+. Install it with `npm install -g https://github.com/nanaagyei/noetherkin/releases/latest/download/noetherkin.tgz`, the tarball attached to the latest GitHub release. From a checkout, `npm install` (the `prepare` script builds it) and `npm link` do the same; contributors can also use `npm ci` and `npm run build` and run `node dist/cli/main.js`. Noetherkin is not published to a package registry and, under ACP-012, will not be: the capabilities install into an agent, and the controller is built from source. A global install from a git URL (`npm install -g github:...`) currently fails under npm 11: the preparation install npm runs for a git dependency inherits the outer `--global`, links the temporary clone globally before any package script runs, and leaves a broken install. Reproduced 2026-09-24 with a local `git+file://` URL; not fixable from `package.json`. New learners start with `noetherkin setup`.

## Commands

| Command | Behavior |
| --- | --- |
| `setup` | Report the environment (Node, platform, Git, role hosts and the bound project's toolchain), then, in a direct terminal and one confirmed step at a time, install the skills and start `init`. Noninteractive runs only report. Safe to rerun. |
| `help [<command>]`, `<command> --help` | Show the overview or one command's usage. A usage error prints only that command's usage. |
| `skills list`, `skills install [--host <id>] [--global \| --target <dir>] [--skill <id> ...]` | List the portable skills, or install them. Without `--host`, installs for every detected agent; `--global` targets `~/.claude/skills` and `~/.agents/skills`. Run inside the Noetherkin checkout without `--global` or `--target`, it refuses and says how to choose a target. |
| `adapter-handoff --handoff <token>` | Review and approve an action an agent prepared; see below. |
| `competency show <id>` | Show a competency and its advisory graph neighbours. |
| `init` | Propose and, in a direct terminal after consent, publish bootstrap state. |
| `status` | Show identity, mode, onboarding, current selection, record counts, and validation coverage. |
| `tracks` | List the 34 versioned advisory tracks and their required competency scopes. |
| `track show <track-id>` | Show outcomes and all editorial project tiers with transparent support metadata. |
| `track select <track-id>` | Explicitly select or switch the active track; a switch creates pending alignment. |
| `track align` | In noninteractive use, report the exact alignment proposal. In a direct terminal, authorize an exact-scope longitudinal assessment and manager review, then adopt the scope only after a `continue` outcome. |
| `projects --track <track-id> [--stage early\|intermediate\|advanced]` | Browse track recommendations without treating tiers as level gates. |
| `validate` | Validate parsing, twelve schema types, references, catalog pins and supported state integrity. |
| `migrate --to 3.0 --dry-run` | Report every proposed protocol migration change without writing. |
| `migrate --to 3.0` | After interactive learner authorization, publish the transactional 2.0 to 3.0 migration. |
| `doctor` | Diagnose retained locks, pending publication, receipts, snapshots, and invalid state. |
| `doctor --recover` | Review and explicitly authorize bootstrap or lifecycle recovery. |
| `onboard` | Confirm scope, obtain a bound all-unassessed baseline, and complete onboarding. |
| `project select <project-id> --source <path>` | Attach any attachable catalog project after origin, cleanliness, revision and path checks. |
| `project select <project-id> --clone-to <path>` | Explicitly clone and attach a catalog project after interactive consent. |
| `map init`, `map check`, `map status` | Create a project-derived template, check the learner-authored map, and report read-only whether this exact map was checked at the current source revision (`absent`, `incomplete`, `unchecked`, `checked`) with the paths it cites. |
| `task assign`, `task begin` | Assign the next task from the bound project's curated pack (for example `pet-type-integrity` for PetClinic or `deselect-unmatched` for pytest, or the next forge task in sequence), then start it. |
| `task attest --criterion <id> --file <notes>` | Record a check only another person can perform, such as an outside quickstart, against the exact submitted work revision. Task review requires it for criteria the pack marks. |
| `forges [--track <id>]`, `project select <forge-id> --source <dir>` | List forge specifications, optionally only those aligned to a track, and bind one to a new or empty learner-authored directory. Nothing is cloned. |
| `forge new <id> [<dir>] --track <id>`, `forge check <dir>` | Authoring, no workspace needed. `forge new` scaffolds `catalog/forge/<id>.yaml` and a first task template under `tasks/forge/<id>-core/`, never overwriting. `forge check` applies the catalog's forge rules to that layout and reports every problem at once, each with a `Try:` line; any error exits 1. The authoring guide is `docs/forge-authoring.md` in the repository. |
| `report [--out <file>] [--format html\|md\|json] [--include-drafts]` | Write a shareable progress report derived from the workspace records: identity with effective level and standing, competencies grouped by finding with their cited evidence, completed tasks with reviews and the highest assistance used, a timeline, and limits. Read-only and lock-free: nothing is written into the workspace state, and the file is refused inside `.apprenticeship/`. It replaces only a file an earlier report wrote. Every non-learner role is labeled simulated, forge work is described as learner-authored software built in a simulated process, stale records are marked stale, a fixture workspace is labeled as one, and validation problems are listed rather than hidden. The advisory view is never included, and nothing is shown as a score or percentage. HTML is one self-contained file with no external requests. |
| `task scope` | List the files the current task's frozen `investigation_paths` globs select inside the bound source; matches that resolve outside it are reported as rejected. |
| `task submit-design`, `task submit-change`, `task test`, `task help` | Gate design, snapshot learner work, run focused tests, or request attributed help. A forge task snapshots every non-ignored file of the learner's repository and takes the learner's declared `--command`. |
| `review code`, `review task`, `review performance` | Publish bound peer, team-lead and manager judgments. |
| `next` | Derive the phase and invoke safe no-input handlers; otherwise report the explicit command needing learner input or confirmation. It also adds a labeled `advisory` block (ACP-014): the competencies tied for first attention and why, the forges or curated packs that exercise them, blocked and contested items, and any stale advisory it replaced. The block is derived, not evidence, and gates nothing; the full view is written to `.apprenticeship/advisory/attention.yaml`, which is safe to delete. It also shows `learning_log`: the date and first line of the latest dated `## YYYY-MM-DD` entry in the learner's `.apprenticeship/knowledge/learning-log.md`, or null. That is the learner's own words, read-only, and not a verified fact. |

## Role judgments

`onboard`, `track align`, `task submit-design`, `task help`, `review *` and `next` ask a model for one bounded role judgment. Choose the model host with `--role-adapter codex|claude`, or set `NOETHERKIN_ROLE_ADAPTER`. Otherwise `--codex-bin` or `--claude-bin` implies that adapter, and failing that the CLI uses the first of `codex`, then `claude`, that it finds working. If none is available the command fails with `ROLE_ADAPTER_UNAVAILABLE` and says how to install one or choose one. The check runs before any consent prompt, so you never confirm an action that cannot run. In a terminal, a line on stderr says which role and adapter are being asked. `--model` pins a model for either adapter, and `--codex-bin` or `--claude-bin` (or `NOETHERKIN_CODEX_BIN`, `NOETHERKIN_CLAUDE_BIN`) points at a specific binary.

The Codex binary is resolved in this order: `--codex-bin`, then `NOETHERKIN_CODEX_BIN`, then `codex` on `PATH`, then the binary bundled with the ChatGPT desktop app (`/Applications/ChatGPT.app/Contents/Resources/codex`) as a last resort. `setup` and `doctor` show which binary each role host uses, why it was chosen, and any other installed binary for that host. If Codex answers that it is not signed in, the command fails with `ADAPTER_AUTH_REQUIRED` and tells you to run `codex login` or choose another binary or adapter; Codex's raw output is kept in the diagnostic's `detail`, shown only with `--json`.

Both adapters send the same prompt and closed output contract, run with tools disabled and without user or project settings, and return output the controller validates again before anything is published. The Claude adapter runs `claude --print --output-format json` in safe and restricted mode with `--tools ""`, an empty MCP configuration and no saved session. A role judgment is never consent and never publishes by itself.

Every command accepts `--workspace <existing-directory>`, `--json` and `--help`. Init defaults to the current directory. Inspection walks upward to the nearest workspace; an explicit path takes precedence, and a directory that is not yet a workspace reports `WORKSPACE_NOT_INITIALIZED` with the command to create one. Track and project catalog browsing can run without a workspace. Human output is compact text; `--json` output keeps the documented shapes.

Initialization creates an unselected `current-track.yaml`. Onboarding refuses to complete until the learner explicitly selects a track. Initial onboarding aligns universal core plus the track's required competencies. Switching later updates recommendations immediately but leaves evaluation scope pending; existing tasks remain valid and promotion is blocked until a fresh scope agreement, longitudinal assessment and manager performance review support alignment.

For initialization, inputs can be entered interactively or supplied as flags:

```sh
noetherkin init --workspace /absolute/workspace \
  --name "Your name" --goal "Understand and debug a backend" \
  --assistance-max 3
```

Repeat `--goal` for multiple goals. The assistance ceiling is an explicit integer from 0 through 7, not an inferred learner level. The terminal displays the proposed workspace identity and six principals: learner, onboarding coordinator, project curator, peer engineer, team lead and manager. Typing `initialize` grants consent to that registry and bound operation. Any other response publishes nothing. There is no `--yes` or actor override.

Without a terminal on stdin and stderr, complete inputs produce a proposal and exit 3; missing inputs exit 2. A terminal is a direct local-user interface, not a way for an agent harness to impersonate the learner. Unenforceable harnesses must retain the proposal for review. This release has no unattended adapter publishing API.

## Capability adapter handoff

Noninteractive `init`, `track select` and `onboard` return a proposal (exit 3) whose `data.next_action` has `kind: terminal-handoff` and an exact `command`. Generic, Codex and Claude Code capability adapters return the same kind of command:

```sh
noetherkin adapter-handoff --workspace <workspace> --handoff <token>
```

The handoff token binds the proposal to the resolved workspace and expected canonical state. It is transparent proposal data, not authorization. Run it in a direct learner-controlled terminal, review the displayed action and proposal digest, then type the requested confirmation. Noninteractive execution never publishes. If state changed since preparation, the controller rejects the stale handoff and the host must prepare a new one. The derived advisory directory (`.apprenticeship/advisory/`) is excluded from that check, so regenerating the advisory never stales a handoff.

Initialization writes only `.apprenticeship/` records and transaction artifacts. It does not edit AGENTS.md, clone a repository, create evidence or choose a project. Repeating intact commands returns no-change where the lifecycle already records the result. Conflicting identities, inputs, revisions or operation IDs are errors. Later state is never reset by init.

The focused test command comes from the task pack: the PetClinic pack fixes it to `./mvnw -pl spring-petclinic-customers-service test`, the pytest pack to `python -m pytest testing/test_session.py testing/test_main.py`, and the textlint pack to `pnpm --filter @textlint/config-loader test`. A program given as a path, such as `./mvnw`, runs from the checkout; a bare name, such as `python` or `pnpm`, runs from the learner's `PATH`, so the learner prepares that environment (a virtual environment, or `pnpm install`) as the pack's testing expectations say. A forge task takes the command the learner declares with `task test --command`. Its exact output, exit status, timestamps, selected base commit or snapshot and submitted change revision are retained under `apprenticeship-artifacts/test-runs/`. Docker Compose and full-stack startup are outside the PetClinic task.

A rework outcome from `task submit-design`, `task test`, `review code` or `review task` adds a `remediation` list: the prerequisite competencies of the task's primary competencies to revisit, from the competency graph ([selection model](selection-model.md)). It is advisory and records nothing.

## Output and validation coverage

JSON output is one object on stdout with `command`, `outcome`, `coverage`, `data`, and `diagnostics`. Interactive prompts use stderr. Diagnostics contain `code`, `path`, and `message`, and may carry a `detail` with raw supporting output, such as a role host's error text. Human output never prints `detail`.

| Exit | Meaning |
| --- | --- |
| 0 | Success or no-change for the stated coverage. |
| 1 | Invalid state or operational failure. |
| 2 | Invalid command, missing input, or denied consent. |
| 3 | Proposal only, a held lock, or recovery required. |

`coverage: bootstrap` verifies initialized live records against the original consent, immutable snapshots, and initialization receipt. Administrative E0 appears only when that validation succeeds. Cache mismatch is an error; reads do not repair it.

`coverage: simulation` applies to the supported PetClinic journey. It checks publication history, role permissions, immutable task fields, legal transitions, design/review revision binding, assistance attribution, content-addressed artifacts, evidence verification and completion gates. Standing is read from the validated cache; Phase 6 remains administrative E0/all-unassessed because one task does not automatically create a longitudinal assessment.

`coverage: catalog` identifies bundled catalog browsing only. Candidate metadata gaps are displayed rather than inferred, and no opaque fit score is calculated. PetClinic, pytest and textlint have bundled curated task packs; other attached projects hand off to portable task assignment and never expose PetClinic commands.

## Recovery

Run `doctor` first. A live lock owner must finish or be investigated; time elapsed never authorizes lock removal. `doctor --recover` can reclaim a provably dead process on the same host after explicit consent. Unknown owners, malformed owner metadata, and interrupted lock reclamation remain blocked for manual inspection.

A durable prepared manifest exposes an `observed_checkpoint` showing whether each path is on its old, new or absent side. It allows doctor to propose one of three actions:

- **complete:** all retained candidate snapshots validate, and each current file is absent or exactly the proposed bytes;
- **cleanup:** the exact committed receipt and all files verify, so only the pending marker needs removal;
- **rollback:** a candidate cannot be recovered and no receipt committed. Restore existing files byte-for-byte from retained old snapshots and remove only transaction-created files that still match the proposed side.

Recovery rechecks the reviewed checkpoint fingerprint under the lock. Manual edits to a half-written path make it neither side and stop recovery as a conflict. Rollback reads retained old snapshot bytes; it never rebuilds or normalizes them. External edits, unknown state files, conflicting receipts and ambiguous metadata are preserved and block recovery. Corruption after a committed receipt never triggers rollback.

A crash before a durable manifest may leave staging snapshots or temporary files. Their intended operation cannot be established reliably. The CLI preserves them and reports invalid/ambiguous state; it does not fabricate a manifest or recursively erase the directory. Interrupted cleanup can likewise leave empty staging directories requiring inspection.

## Filesystem limits

Publication targets single-user local filesystems on macOS, Linux and Windows that support file fsync, atomic rename and atomic hard-link creation. On macOS and Linux the containing directory is also fsynced after each install. Windows has no directory fsync, so on Windows the workspace must be on a local NTFS volume, and the durability of directory entries rests on NTFS metadata journaling (ACP-018). That assumption has not been tested against power loss. The runtime checks the required primitives and fails closed on errors. A missing durability primitive, for example on a FAT32, exFAT or ReFS (Dev Drive) volume without hard links, produces an initialization proposal before canonical records are written. Filesystem type cannot be proven portably; network/distributed filesystems are unsupported even when their calls appear to succeed. On Windows, renames and deletes are retried for about 2.5 seconds when a virus scanner or indexer briefly holds a file open. WSL 2 with the workspace inside the Linux filesystem is an equally supported alternative.

CI runs the full runtime suite, including process-kill crash recovery and terminal consent, on Ubuntu, macOS and Windows. Other platforms support inspection/proposals where Node and temporary locking are available.

On Windows, role hosts installed by npm are `.cmd` shims (`codex.cmd`, `claude.cmd`). The CLI resolves them through `PATH` and `PATHEXT` and starts them through `cmd.exe` with each argument escaped. A forge task's declared `--command` runs in the platform shell: `/bin/sh` on macOS and Linux, `cmd.exe` on Windows.

The workspace directory must permit temporary sibling lock metadata. State paths and inspected local artifact paths reject symlinks, traversal, and root rebinding. Local artifacts are never executed or remotely fetched. JSON-compatible YAML is accepted with strict duplicate/tag/alias rejection; numeric input must use finite JSON number syntax, with integers inside JavaScript's exact integer range. Writers emit canonical UTF-8 JSON into `.yaml` files.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall