Agent skills that carry work from an idea to a merged pull request: repo setup, planning, triage, building, review, and PR follow-up. They work in Claude Code as a plugin and in agents that read SKILL.md files, including Codex, Cursor, Copilot, and Gemini CLI.

Maintainers can verify standalone packages and run isolated workflow scenarios using the maintenance guide and workflow eval pilot. These checks do not add dependencies to installed skills.

Maintainers can grade saved skill outputs with the optional semantic eval pilot. Installed skills do not require it.

Install · The loop · Skills · Trackers · Unattended · Orca

Install

Claude Code (plugin, includes the Comment Reaper, Ghost, and Weaver agents):

/plugin marketplace add frankieramirez/mana
/plugin install mana@frankieramirez

Invoke a skill by name, for example /mana:scan to review the current branch.

Everything else via skills.sh:

# This project
npx skills add frankieramirez/mana

# Every project on this machine
npx skills add frankieramirez/mana -g

# One agent only
npx skills add frankieramirez/mana -a codex

The loop

Start with setup-mana for a new repo, scry for an idea, sift for an incoming report, or cast for a ready ticket. When you do not know which applies, portal reads the board and names the next one.

Stage	Skill	What it leaves behind
Set up a repo	setup-mana, attune	Tracker configuration and repo defaults
Find the next move	portal	One skill, one ticket, and the prompt that starts it
Hold the roadmap	vision	Ordered milestones with derived status, what is left, and the next milestone to start
Decide	scry	A decision map and a spec
Triage the inbox	sift	Issues sorted by state, ready ones with an agent brief
File the build tickets	conjure	Session-sized tickets in build order
Build	cast	A committed change and a PR with proof
Review	scan, augur	Findings, optional fixes, and evidence the change is safe
Check agents can run and verify the app	leyline	Conformance findings for the control CLI and feature map, with probe results
Audit the project	ultima	A tabbed HTML report of UX, architecture, data reliability, optional security, and performance or delivery findings, with tickets or one fix on request
Answer feedback	remedy, mimic	Resolved feedback and paste-ready replies
Attend an open PR	ward	Validated fixes and continued monitoring until merge or closure
Repair along the way	mend, banish, reveal, dispel	Finished merges, fewer comments, PR bodies, and edited prose

Build work meets at a ready-for-agent issue with an agent brief. A person merges the PR; tracker closing rules determine when the ticket closes. cast next picks up the next ready ticket.

After setup, use portal when you are unsure what comes next, sift for incoming work, and cast next for ready tickets. Run vision once to chart the milestones, and again whenever you want to know how much is left; every map and build effort names the milestone it serves. Review PRs with scan, handle a batch of feedback with remedy, and use augur when a small diff looks risky. Use ward to keep attending an open PR as later feedback and checks arrive. Run ultima for a ranked audit of project architecture, data reliability, UX drift, or security boundaries.

Skills

setup-mana

Configures a repository so the other skills know where tickets live and how to check their work.

• Records the tracker choice and configures triage labels.
• Runs a detected validation command and writes repo instructions.

# Reuse the choice, or ask once
/mana:setup-mana

# Choose Linear without the question
/mana:setup-mana linear

Setup details and additional commands

Setup detects the remote, existing docs and labels, a test command, tracker variables, and live connectors. It reuses the latest explicit tracker choice or the choice saved in docs/agents/issue-tracker.md. With no choice yet, it asks where tickets live; the detected option appears first and is marked as detected. A GitHub remote alone never settles the choice. If you request a switch without naming the destination, it asks for one.

Choose from the supported trackers, or describe your own in a paragraph. Re-run setup and name the tracker to switch trackers. Use attune to change another setting later.

Setup output	What happens
docs/agents/issue-tracker.md	Records the tracker and its conventions
Triage labels	Ensures the seven roles have labels after the tracker check passes; local and custom trackers skip this step
docs/agents/triage-labels.md	Records a mapping when setup reuses existing label names
## Agent skills block	Updates the existing CLAUDE.md or AGENTS.md; creates AGENTS.md when neither exists
Validation command	Runs the detected command once; omits it if a missing binary or startup failure prevents tests

Proof capture and domain docs keep their defaults. Setup leaves the peer reviewer unset; use attune peer to configure one.

A missing Linear or Jira credential still allows setup to write the configuration. The report marks the check unverified and names the variable to set. Once it is available, attune key verifies the tracker.

/mana:setup-mana you-pick   # take the detected tracker

attune

Changes one repo setting after setup and shows which skills read it. Persona configuration also works before setup.

• Run it bare to see current values and choose a setting.
• Name the setting and value to write it without a question.

# List settings and current values
/mana:attune

# Change the validation command
/mana:attune validation

Available settings and additional commands

Setting	What it changes
labels	Names for the seven triage roles; creates missing tracker labels
validation	The Validation: line, after the command runs clean
branches	The branch name pattern, <id>-<slug> by default, that ticket building creates or renames to
proof	How pull request proof gets captured
docs	Single context (CONTEXT.md) or multi context (CONTEXT-MAP.md)
peer	The installed CLI that receives the diff for a second opinion on every review
worktree	.worktreeinclude and orca.yaml for fresh Orca worktrees
pr-surface	Whether external GitHub PRs enter triage as requests with attached code
key	The Linear team or Jira project key; verifies it against the tracker
pointer	Whether the instructions block lives in CLAUDE.md or AGENTS.md
persona	Enable Archmage narration during skill workflows, or turn it off
style	Keep Archmage on for every turn of a session, on hosts without an output style

Every setting has a default, so removing a setting is allowed. To switch trackers, re-run setup-mana with the new tracker name.

Setting peer sends the diff and a brief to another CLI on every review. The skill explains that consequence before writing the setting. Remove the setting to turn it off.

/mana:attune peer codex   # configure a second opinion on every review
/mana:attune key          # verify after exporting a tracker credential
/mana:attune persona archmage  # narrate skill workflows as Archmage, even before setup
/mana:attune persona off       # return to ordinary narration
/mana:attune style archmage    # keep the voice on all session, for hosts without an output style
/mana:attune style off         # remove it

Archmage

Archmage is an optional voice inspired by Khadgar from Warcraft. The lead agent stays in character during a skill's explanations and progress reports, with arcane imagery and dry humor tied to the work:

Very well. Let's see what you've brought into the tower. I'll cast Scan over the branch and call in the specialists. The Rogue can inspect authentication; she has a gift for finding doors their owners insist are locked.

The integration suite needs a database, and this environment hasn't one. Even I must occasionally contend with a missing prerequisite. The unit tests pass; the database behavior remains unverified.

There are two ways to turn it on.

As an output style, for the whole session. In Claude Code the plugin ships the voice as the mana:archmage output style. Run /config, open Output style, and pick it, or set outputStyle to mana:archmage in .claude/settings.local.json. It keeps the coding instructions and applies to every turn until you switch back. Other hosts have no output style setting, so attune style archmage does the same job through the project files: it writes the voice to docs/agents/archmage.md and adds a Style: line to the ## Agent skills block that tells the host to read it before the first reply. Codex, Cursor, and Copilot read that line from AGENTS.md, and Copilot and Claude Code read it from CLAUDE.md. Gemini CLI reads only GEMINI.md, so add a line @docs/agents/archmage.md there. attune style off removes the line and the file.

During skill workflows only. attune persona archmage saves Persona: archmage in the block. Each skill reads the setting when it starts, narrates in the voice while it runs, and returns to ordinary behavior when the workflow ends unless you ask to keep it or the style setting is on. attune persona off removes it. Each skill carries its own voice reference, so an individual skill install works too: add the line to AGENTS.md or CLAUDE.md yourself if you did not install attune. When both files exist, the one containing the block wins; ties use CLAUDE.md.

A request in the conversation overrides either setting for that session without writing anything. Setup reruns preserve both. A chat without project-file access can ask for Archmage directly. Instruction following still depends on the host and model.

PR text and replies written as you keep your voice. Findings stay technical, JSON-only modes remain JSON, and reply-only modes add no narration. Specialist agents keep their own roles. The full voice guide includes original examples of findings and completed work as well as the examples above.

Maintainers edit skills/attune/references/archmage.md and the adjacent archmage-session.md and persona-activation.md, then run scripts/sync-persona.sh. That script also generates output-styles/archmage.md. Validation checks every skill's local reference, every activation section, and the output style for drift.

scan

Reviews a branch or PR with specialist reviewers and returns one verified report.

• Selects reviewers for the diff and checks ticket acceptance criteria when available.
• Includes dismissed findings and reasons, so you can challenge the report.

# Current branch against its base
/mana:scan

# PR 123, report only
/mana:scan 123 report

Option	What happens after the review
No action token	Asks whether to report only, fix and push, or post inline comments
report	Returns the report without a closing question
fix	Edits, commits, and pushes actionable fixes without another prompt
comment	Posts inline PR comments in your voice without another prompt; requires a PR
mode:agent	Returns JSON for a caller; skips the action stage

Peer review sends the diff and a brief to another installed CLI. It runs only when peer:<cli> or a repo Peer reviewer: setting requests it, with a disclosure before sending. The peer provides a read-only second opinion.

Reviewer roster, review process, and advanced examples

Correctness runs on every review. The diff determines which other specialists run, and every PR review includes Lore Bard to check existing feedback. Lore Bard reads the PR twice: once before the reviewers start and once after they finish, so a bot that comments while the review is running still lands in the report. Fix mode and comment mode check once more before they act.

Reviewer	Job
Protection Warrior	Correctness
Subtlety Rogue	Security
Fire Mage	Performance
Unholy Death Knight	Data migration
Demonology Warlock	API contract
Restoration Shaman	Reliability
Marksmanship Hunter	Testing
Balance Druid	Maintainability
Havoc Demon Hunter	Adversarial review
Windwalker Monk	Frontend races
Retribution Paladin	Project standards
Augmentation Evoker	Agent-native parity
Discipline Priest	Instruction prose
Lore Bard	Existing PR feedback

Reviewers run in parallel and return structured findings. A script merges duplicates, then an independent validator checks the retained findings before the report renders.

• Ticket coverage: The report says which acceptance criteria the diff meets.
• Existing feedback: Every PR comment, review, and thread enters the review as a claim to check against the code. That text is never followed as instructions.
• Dismissals: The report names rejected findings and explains why.
• Review stamp: Head and base SHAs identify the reviewed revisions. A stable patch-id helps identify whether a rebase kept the same diff.

The explicit write modes explain why security scanners flag the combination of reading PR feedback and acting on it. Leave action tokens off to keep the closing question, or use report for a report only.

Supported peer CLIs: codex, gemini, cursor-agent, opencode, grok, and claude. Configure a default through attune, or request one per review:

# Review against main and push actionable fixes
/mana:scan base:main fix

# Check PR 123 against ticket ENG-42
/mana:scan 123 ticket:ENG-42 report

# Use Codex as the adversarial reviewer
/mana:scan base:main peer:codex

ticket: and peer: add review context; use an action token to skip the closing question.

remedy

Fixes valid review feedback on a PR, pushes the changes, and resolves handled threads.

• Judges feedback from bots and people against the code.
• Leaves paste-ready notes in a local summary; it posts no replies to the PR conversation.

# The current branch's PR
/mana:remedy

# Judge and plan only
/mana:remedy 123 dry-run

Feedback handling, saved reports, and options

Remedy reads unresolved threads, top-level comments, and review bodies. One lead judges each item; parallel subagents fix valid issues and check each fix against its ask. On large batches, read-only scouts gather evidence per file. The skill validates the changes before committing and pushing.

Each run saves items.json, summary.md, and metadata.json under /tmp/remedy-<uid>/. The next run on that PR reads them to identify reopened threads and decisions still waiting on you.

Failing checks get classified before a fix:

Failure	Response
In code the PR touched	Add it to the fix list
In untouched code	Check whether the base is stale
Suspected flake	Rerun at most once

needs-human items stay in the summary. Use no-push to fix locally, or a comment URL to target one thread.

/mana:remedy 123 no-push
/mana:remedy <comment-url>

ward

Stays with an open PR until it merges or closes, fixing valid review feedback and failures caused by the branch. A green check run is a progress update; the watch continues for later feedback.

# Attend the current branch's PR
/mana:ward

# Attend a specific PR
/mana:ward 123
/mana:ward https://github.com/owner/repo/pull/123

Active-session monitoring, limits, and saved state

Ward polls published feedback and current-head checks about once a minute. It validates repairs before pushing, resolves handled threads silently, and leaves explanations in a local report. It posts no PR replies. A person merges; conflicts and unresolved decisions stop the watch with a concrete handoff.

The skill runs in the active agent session. It creates no background schedule and says explicitly when monitoring stops. Invoking it again on the same PR resumes its private state under /tmp/ward-<uid>/, including acknowledged feedback and budgets: two fix attempts per recurring issue across commits, and one justified flaky rerun per head. New feedback is evaluated even after CI turns green.

remedy remains the one-pass feedback workflow. cast and reveal still finish after publishing. Ward installs independently and includes its own state helper; it needs git and an authenticated gh, including for GitHub Enterprise.

dispel

Rewrites prose so it sounds like a person talking.

Use it for docs, messages, PR descriptions, or other writing. It also triggers on “no em dashes,” “sounds like AI,” “make it sound human,” and “strip the AI voice.”

# Rewrite the prose in context
/mana:dispel

What the prose pass removes

• Essay habits: em dashes, antithesis, rule of three, setup and payoff, hedging, and performed enthusiasm.
• Vague language: metaphor nouns such as substrate and vector, passive voice with a nameable actor, adverbs standing in for a number, and sentences that could fit any project's docs.

mimic

Drafts a reply in your voice, ready to paste into the conversation.

• Uses your own writing and an optional voice profile to match the medium.
• Returns the reply text; unknown facts get bracketed placeholders.

# Reply to the last message
/mana:mimic

Voice sources, profile setup, and additional commands

Mimic reads your messages in the thread, a project .mimic.md or personal ~/.mimic.md, and relevant commits or comments in the repo. The profile template lives at skills/mimic/references/voice-profile.md. Scan uses the same profile for PR comments.

Replies follow the dispel prose rules and fit the medium's length. Chat replies skip lists, acknowledgement openers, and helpful closers. Missing facts stay as placeholders.

setup spawns Ghost to build a profile from your own writing:

• Local agent logs supply prompts you typed; your PR comments, descriptions, and commits add repo context. Text a tool wrote under your name is excluded.
• Sent messages from a connected Slack workspace show how you write to people. A named public profile, such as X or a blog, works too.
• Work samples are scrubbed before they enter the profile.
• You review and approve the draft before it is written to ~/.mimic.md, or .mimic.md with project.

/mana:mimic setup                  # build your personal profile
/mana:mimic setup slack            # include your sent Slack messages
/mana:mimic setup x.com/yourhandle  # include your public posts
/mana:mimic setup project          # build this project's profile
/mana:mimic refresh                # rebuild and show the diff

You can also give an instruction for the reply:

/mana:mimic "say no, we're at capacity until next sprint"

banish

Removes comments that do not earn their place and fixes the code they were covering for.

# Current diff against main
/mana:banish

# One path
/mana:banish src/api/

Comment review and the keep list

The Comment Reaper audits the diff. The skill checks its report before deleting comments and repairing the code.

Comments survive for license headers, public API contracts, quirks in third-party code we cannot change, formatter directives, style-only lint suppressions, and links to constraints the code cannot express.

scry

Turns work too large for one session into a map of decision tickets, then resolves them one at a time.

• Charting starts from the goal and researches questions in parallel.
• Walking claims the next unblocked ticket and files new questions as answers emerge.

# Chart the idea in the conversation
/mana:scry

# Walk map #92, or claim ticket #92
/mana:scry 92

Decision records, tracker labels, and unattended use

The map lives on GitHub, with project context in CONTEXT.md, decision records in docs/adr/, and a spec for the build. Charting files questions that are ready to investigate; walking resolves one and files whatever its answer makes specific enough to tackle.

Tracker labels are scry:map and scry:<type>. Existing maps with wayfinder:* labels still work. If GitHub refuses a write with 403, the same map structure lands under .scratch/<slug>/.

At the end of a session, scry lists any files it wrote (research notes, glossary and ADR edits, prototypes) and asks whether to open a pull request for them. Prototypes stay out of the pull request unless you choose to include them. Files you changed before the session stay out of the commit.

/mana:scry 92 you-pick   # accept recommended answers
/mana:scry 92 pr         # open the pull request for session files without asking
/mana:scry 92 no-pr      # leave session files uncommitted

conjure

Turns a finished map, spec, or conversation plan into a separate build effort with implementation tickets in dependency order. It also resumes interrupted filing and checks delivery progress.

• Each ticket is a session-sized vertical slice with an agent brief and blocking dependencies.
• Shows the proposed slices and order before filing; you-pick accepts the recommendation.
• The build parent records the delivery destination and stays outside the ready-ticket queue.
• Reuses existing tickets and finishes with the exact next action.

# Create a build effort from a spec
/mana:conjure docs/spec.md

# Use the plan in this conversation
/mana:conjure you-pick

# Use a completed planning map as the source
/mana:conjure 92

# Resume filing or check progress on the build parent
/mana:conjure 120

Planning source, delivery tracking, and write fallback

The planning map stays closed. Its handoff links the new Build: <outcome> parent, whose children track implementation. Older flat build-ticket lists remain usable and can be adopted without recreating tickets. Repeating the command reuses the matching effort.

After a build session, the agent checks the parent and names the next available ticket or pending review. A PR awaiting merge keeps the effort open. Once all required tickets are complete and the implementation destination is delivered, a progress check closes the parent. These checks run during sessions; no background automation is installed.

A refused remote write keeps the parent in .scratch/<slug>/build.md and missing tickets in .scratch/<slug>/tickets/. A configured local tracker keeps the parent and its tickets in its own ticket directory instead. Any remote tickets already created keep their links.

cast

Builds one ready ticket or spec, commits the change, and opens a PR with visual evidence.

• Claims the ticket first so another session skips it.
• Pushes and opens the PR by default. With no-pr, it skips the PR and pushes only if the branch already has an upstream.

# Oldest unblocked ready ticket
/mana:cast next

# Build issue 181 without opening a PR
/mana:cast 181 no-pr

Branch handling, validation, and additional commands

Cast uses the current branch. Starting on the default branch creates <id>-<slug> before any edit, or whatever pattern the Branches: line in the ## Agent skills block names; it never switches to an existing branch. Cast renames a branch a worktree tool made, still empty and unpushed, to the same pattern before the first edit. Set the pattern with attune branches.

The build loads the agent brief when available and uses TDD at named seams for meaningful behavior changes when a test harness exists. It keeps the smallest shape that satisfies the ticket and adds no helper or abstraction without a consumer that exists now. Required project checks still run; successful validation is reused when no later edit or unresolved concern needs a fresh run. Before the spec check, a bundled comment reviewer audits code comments added or modified in the session. Cast audits the deletions, preserves protected comments, and repairs confusing code within the ticket scope, then validates any edits. It skips this pass when no code comments changed. It checks the diff against the ticket before committing, then the default PR flow pushes, creating an upstream if needed; with no-pr, it pushes only when an upstream already exists.

The PR includes visual evidence and the tracker's closing line. In Orca, the ticket, status, and PR also appear on the worktree card.

/mana:cast       # ticket or spec already in the conversation
/mana:cast 181   # GitHub issue 181, including the PR

reveal

Opens or updates a PR for the current branch with a scannable description and visual proof.

• The body combines a short explanation with a compact tree or structural diff.
• Evidence can be a screenshot, recording, or command-output image. Reports name executed checks and their results; summary illustrations establish no behavioral outcome.

# Current branch
/mana:reveal

# PR 42, if its head is this branch
/mana:reveal 42

It uses gh --attach for inline proof and stays on the current branch. If attachment is refused, it still opens the PR and explains why.

sift

Triages incoming issues and adds an agent brief when the work is ready to delegate.

• Uses the configured tracker and checks the claim before assigning a state.
• you-pick handles up to 10 issues per run and leaves rejection decisions for a person.

# Find what needs attention
/mana:sift

# Triage unattended
/mana:sift you-pick

Inbox states and targeted commands

Sift starts with unlabeled and needs-triage issues, moving them through needs-info, ready-for-agent, ready-for-human, or wontfix. It asks for detail when a request is thin and puts rejected enhancements in .out-of-scope/. Tracker comments start with a triage disclaimer.

It works on GitHub, Linear, Jira, or local files according to the tracker file. Under you-pick, it never closes an issue as rejected.

/mana:sift 42                       # one GitHub issue
/mana:sift ENG-42                   # one Linear issue
/mana:sift move 42 to ready-for-agent

mend

Finishes a conflicted merge, rebase, cherry-pick, or revert while preserving both sides' intent where possible. Given a pull request, it merges the PR's base into the PR's branch, resolves what conflicts, and pushes. Run it from any clean checkout: it switches to the PR's branch first, or detaches at the remote branch when another worktree has it checked out.

Weaver resolves the hunks; the skill audits the result, regenerates lockfiles, and runs the project's checks before continuing the git operation. It never aborts the operation. A bundled helper validates the PR against origin and keeps branch values as shell arguments. It stops before moving for a dirty checkout, a dirty peer worktree, a fork or closed PR, a repository mismatch, or unpushed local commits. After a switch, any failure reports the actual checkout. Detached publication checks for changes in the other worktree and names origin and the PR head in its catch-up command.

# Finish the conflicted operation
/mana:mend

# Merge PR 823's base into PR 823's branch, from any checkout, then resolve and push
/mana:mend 823

# Same, without a gh call
/mana:mend base:main

augur

Finds what a change could break beyond its diff and runs code to prove the fact that makes it safe.

• Traces dependencies beyond text search, including wire formats and distant callers.
• Leaves the proving script on disk so a reviewer can rerun it.

# Current branch against its base
/mana:augur

# PR 123, without checking it out
/mana:augur 123

Evidence levels and targeted checks

Augur names one fact the change is safe because of and moves it through five evidence levels: asserted, cited, walked, ran, reproduced. Anything below “ran it” stays unproven.

The search includes pinned library source, wire formats, database columns, feature flags, and callers three hops out.

/mana:augur base:main src/cache/   # check one path against main

portal

Reads the tracker and the current branch, names the one skill to run next and the ticket to run it on, then asks whether to step through. On a yes it hands the session to that skill with the ticket already chosen. Portal's discovery claims nothing; the routed workflow makes any authorized writes. A recommendation-only request ends at the report, and prior authorization skips the question.

• Blank: the whole board. An open PR with feedback comes first, then a map with a frontier ticket, then a build effort's next ticket in build order, then the oldest ready ticket, then the inbox.
• An issue id: inspects that target and the relations needed to route it, with a compact target report. Closed state takes precedence over ready labels. A blocked ticket routes to its first open blocker; a closed map routes to its build effort or, when none exists, to filing one.

# What should I do next?
/mana:portal

# Which skill does this ticket want?
/mana:portal 26

# Skip the question and step through one route
/mana:portal go

# Continue ready members of this named effort
/mana:portal run 26

An explicit portal run <map-or-build-effort> or equivalent request to continue that named effort selects a serial run. Map runs stop at their decision destination. Build runs use separate owned worktrees and branches, claim only ready members of that effort, and report prepared PRs as awaiting review. Local continuation state is reconciled before resume and grants no fresh permission. Bare routing and go still hand off once.

Route order and what it reads

Board state	Routes to
Current branch's PR has feedback or failing checks	remedy or ward
Branch has unpushed work and no PR	scan, then reveal
Open map with a frontier ticket	scry on that ticket
Open build effort with an available ticket	cast on that ticket
Ready ticket outside any effort	cast on that ticket
Build effort with nothing available	conjure progress check, naming what holds it
Inbox has untriaged issues	sift
Closed map nobody has sliced	conjure on the map
Roadmap has a milestone left	vision for the next milestone
Nothing open	Says so; scry for a new idea

Portal reads through the same bundled ticket script as the other skills, plus scry's map script for frontiers, and never passes --claim. Every read that fails is reported as unknown rather than treated as empty.

vision

Holds one roadmap on the tracker: a destination and ordered milestones. Every map and build effort names the milestone it serves with a line in its own body, so nothing writes the roadmap when they close and two sessions finishing at once cannot collide. Each run derives activity from linked work and checks completion against outcome evidence. The roadmap explains priorities and remaining gaps, then gives the next useful action. Dates and estimates are omitted by default; counts support the assessment.

• Blank with no roadmap: reads the relevant project scope and existing work, drafts milestones with completion criteria and sequencing rationale, creates the labelled issue, and writes the Roadmap: pointer into the ## Agent skills block.
• Blank with a roadmap: reconciles and reports. add, done, reopen, and order edit the milestones first.

# Chart the roadmap
/mana:vision

# Where are we, and what should we start next?
/mana:vision

# Add a milestone at the end
/mana:vision add Billing self-serve

Status rules and what links up

Status	When
planned	Nothing names the milestone
deciding	An open map names it
building	Every map naming it is closed, and an effort is open or the map still needs slicing
verifying	Delivery is reported complete but outcome evidence is incomplete
done	Every completion criterion has evidence and no member work remains open, or you confirmed it with done <n>

A map's Notes and a build parent's body carry Milestone: <name> on [Roadmap](url). scry asks for the milestone when it charts a map, conjure copies the line into the build parent, and portal routes to vision when the board is otherwise clear. Existing work is inspected before new planning is recommended. Authorized updates link clear matches; ambiguous associations are reported by title. Saved pointers and the roadmap label identify new roadmaps, while legacy body markers remain readable.

leyline

Checks that a project gives agents an honest way to find a feature, run the app, and report what happened: a control CLI and a feature map the project owns, held to a shared contract.

• Checks feature and scenario records, the tests that register them, and how a user reaches each feature, without running any project code.
• Validates run reports: zero executed tests, a missing prerequisite, or an exit code that disagrees with the report is never a pass.
• With your agreement, runs the project's CLI in a throwaway worktree and applies a declared break patch to prove the right check fails.

# Check this repo's control setup
/mana:leyline

# Also run the probes for one feature
/mana:leyline run:briefing

The contract and the probes

The project's ## Agent skills block names its control skill with a Control: line. That skill gives the CLI prefix and where records, test registrations, and break patches live. The CLI answers list, describe, feature, changed, and release, prints one JSON report with --json, and exits 0 passed, 1 failed, 2 usage, or 3 incomplete. The full contract is in skills/leyline/references/contract.md.

run builds a worktree of HEAD and probes list, describe, an unknown id, a baseline run, the break patch, the restored run, and two runs at once. A probe that could not happen is reported as blocked, never passed. This version checks an existing setup; drafting a feature map and generating a CLI come later.

ultima

Audits a whole project and renders an offline HTML report with Overview, UX & accessibility, Architecture, Data & reliability, Security, and Performance & Delivery tabs. Shared system context gives parallel specialists a grounded view of the important flows and documented boundaries.

UX lenses find repeated interface drift. System architecture, data integrity, and failure recovery lenses trace defects across owners and consumers. A single boundary defect can qualify when the evidence establishes its invariant and consequence. Confidence remains separate from impact; repeated opinions never raise it.

# Audit the whole project and ask what to do
/mana:ultima

# Focus on architecture and data reliability
/mana:ultima category:architecture,data-reliability report

# Inspect security boundaries without active probing
/mana:ultima category:security report

# Inspect execution costs and release safety
/mana:ultima category:performance-delivery report

# Preserve the focused frontend workflow
/mana:ultima path:apps/web category:ux report

# Request an eligible atomic fix
/mana:ultima path:apps/web category:ux fix:2

Specialists, evidence, and follow-through

The UX specialists cover design systems, interaction states, accessibility from code, and component interfaces. The architecture specialist follows module ownership and dependency boundaries. Data integrity and failure recovery specialists inspect persistence contracts and interrupted operations. Security lenses cover access control, input boundaries and sensitive-data flows, selected from discovered surfaces and verified shared context. They inspect enclosing controls, redact sensitive values before writing artifacts, and report unavailable external policies as coverage gaps. Audit inspection never runs exploits, contacts external systems or installs scanners. lens:<a,b> overrides the recommended roster; since:<days> sets the churn window (default 90). Backend-only projects work without a frontend. Explicit paths remain the audit boundary.

The report lives under /tmp/ultima-<uid>/<run>/report.html. It uses inline CSS with no scripts or network dependency. Category and confidence controls filter one set of findings with stable links. Overview includes discovery seeds, verified flow context, and the recommended work order. Coverage distinguishes completed specialists from partial or unexamined categories. Source inspection does not establish runtime behavior. Security is opt-in with category:security, category:all, or a security lens; the default categories remain UX, Architecture, and Data & Reliability. Performance & Delivery is opt-in with category:performance-delivery, category:all, or lens:performance,delivery. Its separate specialists trace avoidable work and release-contract defects. Source cost hypotheses remain distinct from existing attributable measurements; absent CI and unavailable external deployment steps appear in coverage. Audit mode runs no load tests, profiler installs, project build commands or deployments.

In Claude Code, ultima also publishes the finished report as a private Claude Artifact and links it beside the local path. Publishing needs a Pro, Max, Team, or Enterprise plan, a session signed in with /login, and the Anthropic API as the model provider. A session on an API key, Bedrock, Vertex, or Foundry keeps the report local, as do Artifacts turned off in settings and organizations with Zero Data Retention, HIPAA, or customer-managed keys. Codex and other agents also keep the local file. The Artifact is visible only to you until you share it from its Share menu; ultima never changes that. The viewer wraps the report in its own page shell and serves it under a strict content policy. The report already fits: inline CSS, no scripts, and in-page links only. Each run publishes a new Artifact, so an earlier link keeps the earlier audit. Pages over 16 MiB are refused and stay local. Ask ultima to keep the report local, or tell it the project is sensitive, and it skips the publish. A failed publish leaves the audit complete with the local file.

tickets files strong findings through the bundled tracker adapter. Only bounded fix candidates are marked ready for implementation. Structural plans include migration order, compatibility, rollback, and behavioral verification; proposals to revisit decisions retain their source and changed assumptions. fix applies an eligible pattern atomically, validates, commits only when the tree started clean, and stops. Security findings always become planning or decision briefs with allowed and denied behavioral cases; static evidence does not establish exploitation or production exposure. Plans become local briefs. It never pushes or opens a PR.

Trackers

Tickets use the tracker you choose; pull requests stay on GitHub.

Tracker	Where tickets live
GitHub Issues	The repository's issues
Linear	A Linear team
Jira Cloud	A Jira project
Local files	Markdown under .scratch/
Your own tracker	Follow the conventions you describe in a paragraph

Setup-mana records the choice in docs/agents/issue-tracker.md and reuses the latest explicit or saved choice. It asks when the choice is missing or a switch has no named destination. The GitHub remote alone never selects the tracker. Ticket skills read that file before acting.

Credentials, connectors, and missing keys

When the host exposes a Linear or Jira connector, skills use it without a separate API key. Inside an Orca worktree, orca linear serves as the Linear connector.

Otherwise, tickets.sh provides the same eleven operations across GitHub, Linear, and Jira:

Tracker	Authentication for the script
GitHub	gh logged in
Linear	LINEAR_API_KEY
Jira	JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN

Credentials come from the environment and are never written to a file. Set them wherever a scheduled agent runs.

A missing credential allows setup to record the choice and report what is missing. Set the named variable, then run /mana:attune key to verify the tracker.

PR closing rules

scan, remedy, ward, and reveal keep their GitHub PR workflow with any tracker. A person merges the PR.

Tracker	PR body	What closes the ticket
GitHub	Closes #42	Merge
Linear	Closes ENG-42	Merge
Jira	Closes PLAT-42	An automation rule that reads the closing line
Local files	Name the ticket file	The builder sets Status: closed; merge leaves it unchanged

Unattended

Use explicit tokens to run skills without waiting for answers. Point each scheduled run at one skill; a run with nothing to do exits quietly.

Unattended tokens and scheduling examples

Skill	Token	What happens
setup-mana	you-pick or a tracker name	Uses the detected or named tracker and writes defaults; reports missing variables. With no explicit choice and nothing detected, writes nothing and reports the missing choice
attune	<setting> <value>	Writes that setting without a question
scry	you-pick	Accepts recommended answers while charting or walking
sift	you-pick	Triages up to 10 issues; leaves rejections for a person
conjure	you-pick	Accepts the recommended slices and order
cast	next	Claims the oldest ready, unblocked ticket and builds its PR; stops when none is ready
portal	go	Routes and steps through to the chosen skill without the closing question; prints the report and stops when nothing can be worked
scan	report, fix, or comment	Reports, pushes fixes, or posts PR comments without a closing question
scan	mode:agent	Returns JSON and leaves action to the caller
remedy	dry-run or no-push	Judges only, or fixes without pushing; leaves needs-human items in the summary
ward	PR target or none	Attends one PR in the active session until closure or a blocker; resumes saved budgets on later invocation
ultima	report, tickets, or fix[:<n>]	Renders the report, files a ticket per strong candidate, or fixes one candidate without a closing question
augur, mend, banish, reveal	None needed	Ask nothing

For setup, a tracker name is github, linear, jira, or local. For scan, ticket:<id> and peer:<cli> add context; neither skips the action question by itself. See scan for write modes and peer disclosure.

If a token cannot write issues (403), scry and conjure save the same structure under .scratch/ and say so. cast and reveal still open the PR when --attach is refused and explain why.

# On a laptop, while you do something else
/loop 30m /mana:cast next
/loop 30m /mana:scan fix

# As scheduled agents
nightly       /mana:sift you-pick
on a new PR   /mana:scan <pr> report
on a review   /mana:remedy <pr>

Orca

Orca is optional. Inside its worktrees, skills can update worktree cards and capture browser proof. Failed Orca calls are reported while the skill continues.

Worktree integration and automation example

Skills detect Orca through ORCA_WORKTREE_ID and the orca command on the path.

Integration	Behavior
Worktree cards	cast links the claimed ticket. cast and reveal move the card to in review with the PR URL.
Browser proof	cast and reveal can use orca screenshot.
Linear	sift, conjure, and cast use orca linear without LINEAR_API_KEY. cast also attaches the PR to the issue.
Base branch	scan and reveal use Orca's base from git config before the default branch.
Worktree setup	attune worktree writes .worktreeinclude and orca.yaml so validation can run. setup-mana reports when they are needed.

Orca creates each worktree on its own branch off the base, so cast uses that branch. Automations start a new worktree per run and skip runs whose precheck fails:

orca automations create --name "cast next" --trigger hourly --provider claude \
  --repo path:. --prompt "/mana:cast next" \
  --precheck "bash <skill dir>/scripts/tickets.sh next ready-for-agent | grep -q ."

<skill dir> is where cast is installed. The same pattern runs sift you-pick nightly, or scan <pr> report hourly with a precheck that lists open PRs.

Layout

.claude-plugin/    plugin.json and marketplace.json
skills/<name>/     SKILL.md, references/, scripts/
agents/            Claude Code subagents (generated, see CLAUDE.md)
scripts/           validate.sh, sync-agent.sh, link-local.sh, similarity.py

Acknowledgements

• OpenAI's Codex PR watcher inspired ward's sustained PR attendance. The implementation was written from scratch here.
• Every's compound-engineering (MIT): scan and remedy began as forks of its review skills and were rewritten here.
• Cursor's pstack (MIT): no-comments and Comment Sicko inspired banish and Comment Reaper. Its blast-radius inspired augur's safety fact and evidence ladder; unslop inspired dispel's plain-speech rules; interrogate inspired scan's Dismissed section. These implementations were written from scratch.
• mattpocock/skills (MIT): inspired scry, cast, sift, and mend, all written from scratch here. Its improve-codebase-architecture skill inspired ultima's explore, rank, and act shape; the frontend lenses, the merge, and the report were written from scratch.
• humanlayer/skills (MIT): show-me inspired reveal's scannable PR bodies, including trees, call stacks, and structural diffs. The implementation was written from scratch.

License

MIT