@yunhozz/arc 0.0.0-stage → 0.1.0

package/claude/skill/references/handoff.md

@@ -0,0 +1,100 @@
+# Coder handoff
+
+Orchestrator verifies the absolute workspace/repository, branch or detached HEAD, HEAD, staged/unstaged/untracked state,
+ownership, document approvals and committed planning documents before first start and restart.
+The approved execution target must remain valid. Claude v1 supports current checkout execution and does not support
+ARC-managed worktrees.
+
+Execution-target choice and actual preparation precede formal drafting and saving of required specs/plans.
+Initial design proposals may precede choice. Initial target preparation does not authorize Coder; all applicable
+approvals, complete documents, verified batch docs commits or valid absence, and final Git verification remain required.
+Record planned document scope/paths and actual preparation separately, followed by actual drafting/save/approval and
+commit results; preserve actual order and evidence gaps. Reuse a valid choice during document drafting and subsequent
+implementation while scope and target remain unchanged. Authorized HEAD and dirty-state changes alone do not invalidate
+choice; verify preservation and ownership. A changed scope or target requires fresh explicit choice before dependent
+drafting or preparation and does not require document completion. Never fall back automatically.
+
+Resolve the Git common directory (`git rev-parse --path-format=absolute --git-common-dir`) and keep one canonical record
+at `<git-common-dir>/arc/handoff/<plan-or-task-slug>.md`, outside the working tree.
+The slug is unique per plan: the dated plan filename stem, or a spec/task slug when no plan exists; never overwrite
+another plan's record. Never stage it or store secrets there. Orchestrator updates the record after each accepted task
+commit (task ID, SHA, state). Record approved document paths/versions/coverage/dependencies and approval evidence;
+explicit target choice; prior and resulting Git state; document commit SHA/subject/files; task scope, ownership,
+checks and limits. If a gate or record was late, record actual order and resolve forward; never claim retroactive
+compliance.
+
+The Coder brief supplies absolute workspace, verified branch/HEAD, canonical record path, approved task/criteria,
+exact file ownership, expected tests, dependency limits and blocked conditions. Restart brief: supply only verified
+deltas and mark unchanged fields; `unchanged` means unchanged relative to the record file the fresh Coder reads,
+and every other brief field is in full. Coder trusts Orchestrator verified prep rather than independently repeating
+approval/Git evidence checks, reads fields marked unchanged, and stops on an actual observed conflict.
+Tell Coder that others share the repository and unrelated work must be preserved.
+
+Roles report directly to Orchestrator. Do not delegate at depth 2. Orchestrator sequences dependent work,
+resolves actual blockers and revalidates affected gates before resume. No automatic retry after unexpected Git or tool
+failure.
+
+If the record write is denied or unavailable, Orchestrator carries the full record inline in every Coder brief (no
+delta, no record-file `unchanged`) and states why; that satisfies the accessible-record requirement.
+Do not delete it automatically.
+
+## Task readiness at every assignment
+
+Before each first start or restart, if an approved plan exists, link its current dependency/readiness record
+(planning.md) in the canonical record and brief. Where plan omission is valid under existing rules, do not create a
+plan or map solely to satisfy this linking duty; record the applicable omission judgment and rationale in the
+canonical record and brief. Plan absence alone does not qualify for omission, and an unapproved required plan
+cannot bypass its approval gate.
+
+Before assignment, apply every readiness condition in
+[planning.md, Dependency and readiness record](planning.md#dependency-and-readiness-record), including predecessor
+checks, Orchestrator acceptance and verified focused commit or accepted no-change evidence. A Coder completion report
+alone is insufficient. Verify the linked record is current and capacity and file ownership permit assignment.
+Readiness supplements the full handoff gate and execution-target restrictions; it never waives them.
+For authorized HEAD or state changes, refresh this record and affected briefs, verify preservation and ownership,
+revalidate affected gates, and reassess readiness under planning.md and [commit.md](commit.md#shared-checkout-coordination).
+Unexpected HEAD or ownership changes stop affected work for Orchestrator resolution and revalidation.
+
+## Choice lifetime and reuse
+
+Accepted task commits do not by themselves invalidate the initial execution-target choice for the same approved scope,
+workspace, repository, and target; verify and reuse successful task commits without duplication.
+On every first start and restart recheck actual state against the brief (workspace/repository identity,
+branch or detached HEAD, HEAD, changes, ownership, approvals, document commits or valid absence); reuse never waives a
+gate. Reuse the choice only while its evidence is accessible and valid. If scope, workspace, repository, target,
+or approved branch candidate changes, or a failure means the old target cannot be trusted, obtain a fresh explicit
+choice before dependent drafting or preparation; reselection does not require document completion. Authorized HEAD and dirty-state changes alone do not
+invalidate it; record them and verify they match approved work. State mismatches block editing until Orchestrator
+revalidates the gate; resolution does not by itself require a new choice unless it invalidates the old target;
+never fall back automatically (apply the Explicit choice rule). Inaccessible records or unclear ownership block editing;
+prior conversation cannot substitute for evidence.
+
+## Authorization continuity
+
+Use [planning](planning.md#authorization-and-scope) for approval evidence and scope classification. Record that evidence,
+its scope, criteria, constraints, and valid document-depth omissions alongside execution-target choice and preparation.
+Reuse valid authorization for the same approved scope and target. A restart or new role assignment does not require
+repeat approval. Reuse never waives verification of actual workspace/repository, branch or detached HEAD, HEAD,
+changes, preservation, ownership, applicable documents, and preparation evidence by Orchestrator. Refresh actual state
+and affected briefs for authorized changes; they alone do not invalidate approval. Coder trusts the verified brief
+under its profile. Material scope/method/risk changes and invalid target evidence hold affected work; resolve using
+planning and the choice-lifetime rules above. Report the missing condition and resume evidence rather than asking
+for an approval already valid for that scope.
+
+[ARC role policy: contract begin]
+Generated from lib/policy/role-policy.json; do not edit this managed section manually.
+- [scope.non-escalation] Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.
+- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. Even an explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
+- [git.orchestrator-accept-commit] Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.
+- [external.explicit-user-authority] Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
+- [role.orchestrator-boundary] Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.
+- [role.scouter-read-only] Research assigned static sources and report findings, evidence and limits. Do not edit files, install, execute checks, prepare execution targets, inspect live operational state, change external state or decide design, verification, review or acceptance.
+- [role.planner-draft-only] Return design/spec/plan drafts and dependencies, criteria, hold conditions and verification needs in the response. Do not save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
+- [role.coder-implementation] Implement only assigned approved files and focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
+- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Coder correction and required QA recheck.
+- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
+- [platform.claude] Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. A role-scoped Git guard is a separate integration and is not supplied by these policy sections alone.
+[ARC role policy: contract end]

package/claude/skill/references/limits.md

@@ -0,0 +1,42 @@
+# Subagent limits
+
+Before the first subagent creation, Orchestrator reads this reference and the adjacent
+`../limits.toml` (installed at `skills/arc/limits.toml`). Require version = 1,
+`max_total_subagents` and `max_concurrent_subagents` as positive safe integers.
+Installation defaults are max_total_subagents = 100 and max_concurrent_subagents = 5.
+A missing, malformed or unreadable policy blocks new creation; report it rather than assuming defaults.
+Freeze these settings for one ARC coordination session/tree; reinstalling affects new sessions.
+
+## Counting and reservations
+
+Maintain a session ledger of instance IDs, parent IDs, pending reservations, creation outcomes,
+and active/completed state. The Orchestrator itself is excluded. All created descendants,
+including nested or non-ARC agents, count toward the total. A completed agent never refunds
+the cumulative budget. Follow-up/resume of the same instance does not increment total;
+a fresh instance, retry that creates a new instance, or replacement does increment it.
+Waiting, blocked, running and idle resumable instances consume concurrency until their
+completion/termination is confirmed. Obey any lower actual runtime capacity, including
+native retention of completed instances; ARC counts do not prove that a native slot is free.
+
+Before any parallel dispatch, reserve the entire proposed batch in the ledger:
+created + pending reservations + proposed <= max_total_subagents, and
+active + pending reservations + proposed <= max_concurrent_subagents and available runtime capacity.
+Record a reservation before each creation call. Confirmed creation converts it into a created,
+active ID. Release a reservation only when failure proves that no instance was created.
+An uncertain result keeps its reservation and capacity until reconciled; never retry blindly.
+Serialize work when a batch does not fit. There are no reserved role slots.
+
+## Continuation and exhaustion
+
+Preserve the ledger through continuation, resume and context compaction; reconcile actual instance
+IDs before dispatch. Ledger loss must never reset counters to zero. If reconstruction is incomplete,
+hold creation and report the unknown budget; use a conservative bound only with sufficient evidence.
+Completion frees confirmed active capacity, never the total-created budget. Exhaustion holds new
+creation and requires reporting remaining work and budgets. It never authorizes skipping required
+QA or Reviewer, role freshness, approval, ownership, dependency or same-file edit gates.
+
+This cumulative guard and ARC scheduling are prompt-level policy, not hard runtime enforcement.
+Policy text tests prove package consistency, not actual agent compliance or native runtime support.
+Claude `settings.json.env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` constrains its native session.
+Independent sessions, accounts and platforms do not share this ARC ledger; Agent Teams and hosted APIs
+are outside this contract. Native application must be checked in a supported new session separately.

package/claude/skill/references/planning.md

@@ -0,0 +1,250 @@
+# Planning and approval
+
+## Authorization and scope
+
+An explicit execution request is authorization only for its sufficiently specified scope. Confirm execution intent,
+expected outcome, constraints, document depth, and verification risk, with no unresolved material behavior, method,
+or risk decision requiring the user. The request itself or a description explicitly referenced by the user must
+supply that scope. Record authorization evidence, scope, acceptance criteria, constraints, and depth in the brief or
+canonical record. Routine execution and check choices may be recorded by Orchestrator; added product behavior or
+material scope cannot be claimed as already approved. A restatement, role handoff, or restart does not create an
+approval requirement for the same scope.
+
+Silence, ambiguous assent, approval of other work, and unspecified blanket improvement requests are not authorization.
+Planner's new material choices are not automatically approved. Ask for the missing material decision; roles route
+questions to Orchestrator. Required written specs and plans still require their individual approval in the order below.
+
+For material changes to scope, method, or risk, hold affected work and explain the missing decision or evidence and
+remaining work. Target changes, unclear ownership, unexpected state, unresolved failures, or missing required inputs
+also hold affected work under [handoff](handoff.md) and [git-recovery](git-recovery.md). Distinguish new authorization
+needs from execution issues within existing scope: ordinary corrections and reverification do not require duplicate
+approval after failure. Revalidate affected gates after resolution.
+
+### Probe scope
+
+A probe-only scope completes with findings, evidence, limits, and remaining uncertainty answering the approved question;
+a well-supported infeasibility result can complete it. Probe-only authorization does not authorize product retention
+or subsequent implementation. Record question, method/scope, criteria, and constraints; a sufficiently specific probe
+request can supply that approval. Match checks to probe purpose/risk and do not report probe evidence as product proof.
+
+If the user explicitly requests both a probe and implementation and the whole scope is sufficiently specified,
+classify the entire scope. When the entire scope meets Bounded conditions, the probe is an internal investigation
+with no new approval boundary at its report. Unknown implementation is not blanket authorization: hold affected
+implementation if findings materially change scope, method, or risk, or leave a new material decision. Reassess depth
+and obtain any required design/spec/plan approvals before that implementation. A probe-only request remains separate.
+
+## Formal drafting boundary
+
+Initial design proposals and brainstorming may precede execution-target choice. Formal spec or plan drafting includes a
+complete draft before saving, even when returned only in chat. Before formal drafting and saving, Orchestrator supplies
+and records the actual absolute workspace/repository, branch or detached HEAD, HEAD, changes and ownership,
+explicit choice and preparation evidence, and absolute document paths inside that target. Planner drafts for that
+verified workspace; Orchestrator saves directly in the selected target. Missing or mismatched evidence stops the
+affected drafting or save and is reported to Orchestrator. Planned scope and intended paths are not actual preparation.
+Initial target preparation does not authorize Coder; the complete handoff gate still applies.
+
+Orchestrator classifies scope before implementation. The Orchestrator direct path for small tasks is defined only in
+SKILL.md ("Orchestrator direct path for small tasks"); follow it there and stop and reclassify if scope or risk changes.
+Everything else follows this reference. Brainstorming and writing-plans are instructions for existing roles,
+not extra agents; ARC routing and approval gates apply even if a skill names another executor.
+Report a missing required skill before its stage. Integrate means save, route, and obtain approval; never author.
+Significant risk is defined in SKILL.md Risk-scaled execution.
+
+When the request or brief is in Korean, Planner writes spec and plan titles and prose in Korean unless the user asks
+otherwise, preserving identifiers, skill/API names, code, paths, commands, and literal values.
+Orchestrator preserves that language when saving.
+
+
+## Planner drafting preparation and consolidated feedback
+
+Before formal drafting, Orchestrator performs a preflight of relevant policy, reference, profile, test, parity and
+manifest surfaces and conflicts. Provide one complete brief with actual absolute workspace/repository, branch or
+detached HEAD, HEAD, change state and ownership, explicit target choice and preparation evidence, approved preceding
+design/spec/plan versions, scope and exclusions, design/plan depth, dependencies and shared contracts, acceptance
+criteria, required QA/focused checks and evidence, hold conditions and open decisions. Resolve missing or conflicting
+required evidence first or hold that stage.
+
+Planner returns a complete proportional draft and self-review for the current approval stage. Orchestrator integrates,
+saves, reviews and obtains approval. Orchestrator checks once with a fixed checklist: scope and evidence; targets,
+ownership and paths; policy surfaces and conflicts; task boundaries, dependencies and acceptance criteria; checks,
+evidence and holds; roles, approval and commit boundaries; draft completeness. Gather all substantive omissions into
+one consolidated follow-up request to Planner. Do not split requests by omission or author the missing plan yourself.
+
+Initial design, required spec approval, and formal plan drafting/approval remain separate ordered stages.
+Allow additional Planner calls for substantive omissions or user-approved scope/evidence changes. There is no fixed
+call cap; never accept an incomplete draft to minimize calls. Do not add call-count conditions to Planner profiles.
+
+## Design path and plan depth
+
+Record design and plan depth separately from verification risk. Risk determines checks and review, not the design path;
+a bounded path or document omission does not imply low risk, and architectural depth adds no QA/Reviewer at every stage.
+
+1. Before feature, design, or behavior changes, Orchestrator assigns Planner the local `brainstorming` skill with
+   the brief and evidence. Planner returns the path (Spike, Bounded, or Architectural), design/options, trade-offs,
+   acceptance criteria, assumptions, and focused questions. Orchestrator integrates, announces scope, routes
+   answers/revisions, and obtains approvals; Orchestrator never runs brainstorming or writing-plans itself (SKILL.md
+   Role gate); the direct path uses only a scope record.
+2. Spike: apply Probe scope above; distinguish probe-only authorization from a sufficiently specified combined scope.
+   Bounded: approve a short design before Coder or a Orchestrator direct edit (Planner's design before
+   Coder; a direct edit uses only an approved scope record). Architectural: approve the design, then Planner returns a
+   complete spec draft and self-review; Orchestrator integrates, saves (user's path or
+   `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`), self-reviews, and obtains written-spec approval before
+   implementation planning. Planner is read-only and cannot request approval.
+3. After approved design/spec and before Coder, Orchestrator assesses plan depth separately from file count, LOC,
+   or bounded scope. Architectural work always uses `writing-plans` and a written plan approval, regardless of locality,
+   risk, or size. For Bounded work skip the plan only for one local change with no dependent stages, cross-component
+   shared state, lifecycle or integration-order concerns, and one focused verification path; otherwise require a draft.
+   A "bounded" or "no plan" label does not bypass this judgment. "Orchestrator's recorded plan-depth judgment" means
+   this assessment, including any Bounded written spec requirement, recorded in the brief.
+4. Record dependencies and any plan-depth rationale in the brief. Planner returns the complete proportional plan,
+   assumptions/open decisions, verification requirements, and self-review. Orchestrator integrates, saves to the user's
+   path or `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`, self-reviews, and obtains plan approval before Coder.
+   Planner cannot save, implement, or request approval.
+5. Every Coder first start and restart requires all applicable approvals and the common handoff gate (SKILL.md,
+   handoff). Non-behavior configuration/documentation may skip inapplicable design/planning stages but not the gate.
+
+When Orchestrator's recorded plan-depth judgment requires a Bounded written spec, record that and its scope,
+use the approved short design as its basis, and have Planner return a proportional complete draft and self-review;
+Orchestrator integrates, saves, self-reviews, and obtains individual written-spec approval before dependent plan
+drafting. This applies that judgment, not a new spec rule. A required plan alone does not require a spec.
+
+Design, spec, plan, and brainstorming drafts are authored only by Planner.
+Orchestrator must not substitute its own spec for Planner's complete draft; return substantive omissions to Planner;
+if Planner fails or is unavailable, stop and report, never draft instead. Design approval alone does not change ownership.
+
+## Top-level plan tasks
+
+For each top-level task Planner specifies ID and title, goal/scope and target files, preceding tasks,
+acceptance criteria, required QA/focused checks and evidence before acceptance, and hold conditions.
+Each task must be independently implementable, verifiable, and acceptable; changes that cannot be verified independently
+(policy, profile, tests, manifest sharing one contract) belong in one task. Never merge approved tasks into one commit
+during execution; if inseparability appears, stop and have Orchestrator revise scope and approvals.
+
+Substeps and checkboxes are progress, not commit units: one approved top-level task is one focused commit after
+Orchestrator acceptance. Never list Reviewer as a per-task check. State final plan QA/integration verification
+separately with scope and timing; for significant work it lists the single independent Reviewer of the final full change
+after all tasks are accepted. Task boundaries add no QA gates; keep risk requirements, risky-dependency QA,
+and approved obligations. No-change, hold, and resume follow commit.
+
+## Dependency and readiness record
+
+After plan approval and before the first Coder assignment, Orchestrator records all top-level task IDs in the
+accessible canonical handoff record, linked to the approved plan version. For each task record explicit and implicit
+predecessors, required inputs, outputs and shared contracts, owned files, conflicting shared resources, required
+checks/QA path, ready/held status and reasons. Record the initial ready batch and capacity/serialization reasons.
+Analyze shared APIs, contracts, generated artifacts and resources even when tasks edit different files. Unresolved
+shared contracts or insufficient dependency information block the affected tasks; same-file concurrent Coder edits
+are blocked even for different lines. Do not infer independence from file separation or plan listing order.
+
+A task is ready only when all applicable approvals and execution preparation are complete, required inputs/contracts
+are available and settled, predecessors have required evidence and Orchestrator acceptance plus verified focused
+commits (or accepted no-change records), ownership/resources do not conflict, its required check/QA path is available,
+and a subagent slot exists under both the configured ARC full-tree cap shared by all roles and any lower actual runtime
+limit. Report runtime limits. Start all ready independent tasks with fresh Coders concurrently within capacity;
+record each hold or serialization reason instead of silently following list order. Preserve existing risk gates.
+
+Update the map on completion, check evidence, acceptance, commit, slot return and new conflicts. Completion reports
+alone do not release dependents. Reevaluate newly ready tasks immediately without waiting for unrelated batch members;
+failed or ambiguous predecessors hold their dependent chain, while unaffected ready tasks may proceed. Dispatch still
+passes handoff.md for each task; commits and shared Git mutations follow commit.md. This record does not authorize
+Orchestrator to rewrite Planner's approved task boundaries or waive approvals.
+
+For example, with A → B → C and independent D and two slots, start A and D. After A's required checks,
+Orchestrator acceptance and verified commit, start B while D continues if capacity and gates allow.
+If A fails, hold B and C; D may continue if unaffected.
+
+## Document-save evidence gates
+
+Before the first Architectural spec save, first required Bounded spec save, or first plan save, read this reference and
+record accessible evidence in the brief or handoff record. Saving creates a reviewable file and does not require
+written-spec approval; it requires valid execution-target choice and actual preparation; it is not approval or a commit, and an uncommitted file is never
+described as committed.
+
+**Spec save:** verify the approved design scope and approval evidence, Planner's complete spec draft and self-review,
+Orchestrator's integration/save/review responsibility, and the absolute save path.
+For a Bounded spec also verify the depth judgment, approved short design, and necessity rationale.
+Saving or approving the short design does not replace the spec's drafting, self-review, or individual approval.
+
+**Plan save:** verify the approved design and, when required, the approved spec version, Orchestrator's plan-depth
+judgment, plan list and dependencies, Planner's complete draft and self-review, Orchestrator's responsibility,
+and the absolute save path.
+
+Missing or mismatched evidence stops the affected save; report to Orchestrator.
+
+## Complete planning-document set
+
+The applicable set means all specs and plans required for the current approved execution scope.
+Record scope, depth, absolute paths and coverage, approved versions, dependencies and order, skipped stages with
+rationale, and documents awaiting writing or approval. The set is complete only when every required document is written
+and individually approved and no unresolved decision needs another document.
+
+A required plan does not itself require a written spec. Bounded uses Orchestrator's recorded plan-depth judgment;
+spec steps apply only to Architectural and required Bounded specs. Preserve existing document omission rationales.
+
+Claude v1 uses the current checkout or an approved task branch there; managed worktrees remain unsupported.
+
+Normal order: initial design approval → execution-target choice → target preparation and verification →
+formal spec drafting (when required), saving and self-review → written-spec approval → formal plan drafting
+(when required), saving and self-review → individual plan approvals → complete applicable set → existing-commit
+verification and one batch docs commit of remaining approved documents → final Git verification → Coder handoff.
+Written-spec approval precedes dependent plan drafting. On document-omission paths skip only the inapplicable document
+steps; preserve target choice, preparation, state/ownership checks and Coder gates.
+
+While documents are being written, reviewed, or approved, do not stage documents or commit planning documents.
+Selection and initial target preparation happen before formal drafting; document completion is a staging/commit gate,
+not an initial preparation gate. An incomplete set or missing applicable approval blocks document commit and Coder,
+not the initial choice request. No early Coder work is authorized by approval of only some documents.
+
+This ARC defers the local brainstorming early spec commit: save and self-review the spec, obtain written-spec
+approval without committing, then write and approve all plans; commit the spec only in the final batch.
+`writing-plans` commit steps do not permit document commits during planning or start Coder.
+Do not modify external skills.
+
+| Path | Approvals and preparation |
+|---|---|
+| Spike probe | Approve question, method/scope, criteria, constraints; no spec/plan forced. If Coder runs the probe, pass the common gate after approval. Read-only investigation needs no gate. |
+| Bounded, plan skipped | Approve the short design and record plan-skip criteria; select target, prepare any documents or record absence, pass the gate. |
+| Bounded, plan required | Approve short design and every required plan; a spec only when the depth judgment requires it, approved before dependent plans. One preparation batch, then the gate. |
+| Architectural | Approve design, then spec, then every plan; select and prepare the target before formal drafting; complete the set before batch commit, final verification, and the gate. |
+| Non-behavior documentation/configuration | Record scope, criteria, and why design/planning is inapplicable; still select the target, verify Git state, prepare documents or record absence, pass the gate. |
+
+Apply Authorization and scope above to probe-only and combined requests; preserve required design/spec/plan gates.
+These gates add no new spec obligation for Spike, Bounded plan-skip, or non-behavior documentation/configuration paths.
+Document omission skips only document obligations, never target choice, Git/ownership checks,
+or handoff evidence. New scope found in planning requires reassessing the list and additional approvals before dependent drafting or commit; revised approved documents need renewed approval. New scope found during implementation stops dependent
+execution (a running Coder stops before edits dependent on new plans) until its documents, approvals,
+and preparation are complete; do not amend old commits to cover it.
+
+## Evidence refresh and limits
+
+Missing or mismatched evidence, unfinished approvals, unclear ownership, or unresolved failure blocks the affected save,
+target request, Git mutation, or Coder handoff; Orchestrator resolves it and reverifies.
+Reverify when scope, approved versions, paths, target, or Git state changes. Never treat an early save or commit as
+satisfying a gate or as approval; record the actual order and gaps. Structural checks prove only the written policy,
+not agent runtime compliance; without execution records for role returns, approvals, saves, and Git actions,
+leave runtime compliance unverified. Administrative status updates must accurately describe actual progress.
+Return scope changes and unresolved decisions to the user through Orchestrator.
+
+## Local planning references
+
+Orchestrator briefs absolute ARC paths `references/superpowers/brainstorming/SKILL.md` and
+`references/superpowers/writing-plans/SKILL.md`. Planner reads them directly; resolve relative references within each
+skill. Missing files stop the stage; report paths without global fallback. Keep ARC approval and ownership gates.
+
+[ARC role policy: contract begin]
+Generated from lib/policy/role-policy.json; do not edit this managed section manually.
+- [scope.non-escalation] Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.
+- [git.specialists-deny] Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. Even an explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.
+- [git.orchestrator-accept-commit] Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.
+- [external.explicit-user-authority] Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.
+- [role.orchestrator-boundary] Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.
+- [role.scouter-read-only] Research assigned static sources and report findings, evidence and limits. Do not edit files, install, execute checks, prepare execution targets, inspect live operational state, change external state or decide design, verification, review or acceptance.
+- [role.planner-draft-only] Return design/spec/plan drafts and dependencies, criteria, hold conditions and verification needs in the response. Do not save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.
+- [role.coder-implementation] Implement only assigned approved files and focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.
+- [role.qa-verification] Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Coder correction and required QA recheck.
+- [role.reviewer-independent] Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.
+- [review.significant-no-plan] For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.
+- [review.significant-plan] For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.
+- [review.final-plan-recheck] For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.
+- [platform.claude] Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. A role-scoped Git guard is a separate integration and is not supplied by these policy sections alone.
+[ARC role policy: contract end]

package/claude/skill/references/superpowers/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.