arch_skill

Conduct work to verified completion from a finished plan, a partial plan, or a described outcome; the parent is executive architect and cynical reviewer while workers implement, repair, and prove. Outcome or partial-plan intake first runs an executive shaping stage — parallel worker research, a parent trim to the smallest sufficient solution, a lightweight outcome map, one scope approval — and workers never dispatch before observable done-ness and a frozen scope boundary exist. Default execution is the cheap parallel external fleet (Codex gpt-5.6-sol at ultra via agent-delegate, one-word swaps to Kimi, Grok, Cursor, or Claude); native children stay a narrow exception, and Codex usage limits rotate via aim without losing sessions. The `conductor terra` preset keeps its dedicated-worktree, Terra xhigh, three-review, PR-publication, and follow-through path. Not for single bugs, open-ended metric loops, multi-plan epics, plan audits, one delegated task, parent-implemented plans, or read-only opinions.

Run editful Claude, Codex, Cursor Agent, Grok, or Kimi workers as explicit external processes or resumable sessions with exact model/profile resolution and structured receipts. Use when external transport provides a concrete benefit, such as a different provider, a load-bearing exact model/profile, durable exact-session continuation, process isolation, automation, or captured event/final-output artifacts; these are examples, not a closed gate. Route ordinary same-host work directly to the active host's native children when they can satisfy the role. Use exact handles to resume the same external worker. Not for read-only reviews (`fresh-consult`), Codex `-p yolo` reviews, two-model convergence, ordered orchestration, or detached/background delegation.

Monitor and keep alive a long codex goal-mode session that is already running in a tmux pane, until codex's own goal genuinely completes. Watch the pane for usage limits, stalls, or process death; on a real usage limit rotate the aim account (`aim status` then `aim codex use <label>`), then kill, restart, and `codex resume <session-id>` the SAME session, clear the 'Resume paused goal?' menu, and verify it ACTUALLY resumed work on the new account; check on a ~15-min cadence via a background poll, never a tight loop. Use when the user says monitor/babysit/watch/keep-running my codex, keep it going across rate limits, or restart-and-resume it when limited. Not for spawning a worker to do a task (`agent-delegate`), running your own goal-seeking loop (`goal-loop`), a one-off codex review (`codex-review-yolo`), or purging ~/.codex state (`codex-cleanup`).

Implement an existing plan, phase, section, or checklist faster by keeping the plan, audit log, implementation log, proof freshness, and warm plan-backed code review aligned while coding. Use when the user wants plan-backed implementation with less duplicate rereading, fewer repeated checks, compaction-safe progress, native subagent acceleration when available, and continuous review against plan-audit quality doctrine. Not for creating plans, generic code review, external worker swarms, CI policing, deterministic runners, or manually spawning coding-harness executables.

Canonical preflight and operating contract for direct BrowserOS MCP use. Read and apply before the first BrowserOS MCP call whenever an agent will operate tabs, windows, or authenticated pages; upload or download files; capture screenshots; read or mutate web or BrowserOS-managed connector state; recover from BrowserOS errors; or coordinate browser work across agents. It owns non-hidden background operation, foreground-focus discipline, page lifecycle, dispatch-versus-task authorization, target and profile verification, observe-act-verify, timeout recovery, secrets, proof, and cleanup. Use it alongside narrower site skills such as $chatgpt-web, which own the site workflow while this skill owns BrowserOS mechanics. Not for BrowserOS installation or vendor development, generic connectors, or browsing that does not use BrowserOS MCP.

Orchestrate a goal too large for one `$arch-step` plan by decomposing it into approved ordered sub-plans, then running interactive handoffs, same-session `auto-plan` / `auto-implement`, or role-based planner/worker/critic execution. Same-host roles prefer clean native children from durable epic and sub-plan artifacts; the explicit external-harness lane remains available for deliberate provider, exact-model, lifecycle, isolation, automation, or receipt benefits. Use to break up and run a multi-plan epic, continue/resume an epic doc, plan every sub-plan before implementation, or implement an approved epic end to end. Not for a single architecture plan (`$arch-step`), one-pass mini plan (`$arch-mini-plan`), small feature (`$lilarch`), read-only status (`$arch-flow`), or foreign-repo step orchestration (`$stepwise`).

Run the standalone evidence-first bug workflow with a single bug doc: analyze, fix, and review. Use when a request includes symptoms, regressions, Sentry issues, logs, crashes, or 'why is this happening?' and you need to investigate, fix, and verify a bug. Not for feature planning, full-arch work, or open-ended optimization loops.

Query logged-in ChatGPT through one BrowserOS ChatGPT tab after applying the canonical $browseros operating contract and shaping the prompt with $prompt-authoring discipline. Use when the user explicitly wants the ChatGPT web provider/capability, optional attachments, or an exact existing ChatGPT conversation continued. New clean conversation is the default; exact-conversation continuation must be explicit. Defaults to Pro with Extended thinking, runs serially, and waits patiently. Not for OpenAI API work, generic browser automation, automated login, scripts, runners, or hidden harnesses.

Invoke the local Codex CLI with the exact external `yolo` profile (gpt-5.6-sol ultra, fast tier) and captured receipts for an independent review of a substantial artifact or completion state. Use when the user explicitly asks for `codex -p yolo`, an external Codex review, or the profile's exact model/effort/receipt contract. Ordinary same-host Codex reviews should use a clean native child instead. Review-only; requires a concrete artifact or completion target.

Run one or more clean, independent, read-only reviewers for strict pass/fail second opinions, completion checks, consistency audits, or readability checks. Fresh describes starting context, not a CLI: prefer a clean native child of the active host for same-host review, and use an external Claude, Codex, Cursor Agent, Grok, or Kimi session when a concrete provider, exact-model/profile, lifecycle, isolation, or receipt benefit justifies it. Resume the exact reviewer for bounded same-line follow-ups; start a new clean child for a new independent gate. Not for implementation, two-participant convergence, Codex `-p yolo` review receipts, or ordered orchestration.

Orchestrate a prompt-only dialogue between two selected Claude, Codex, Cursor Agent, Grok, or Kimi participants until they converge on a lean plan, architecture, debugging strategy, investigation, design, or concept. Resolve transport independently per participant: use separate clean native children for same-host participants when native model capability suffices, and external sessions for cross-provider or unavailable exact-model/profile needs. Resume each exact participant between rounds; relay through the parent by default. Not for one-shot cold opinions, ordinary code review, ordered implementation loops, or broad idea tournaments.

Write, edit, refactor, or audit prompts and reusable prompt contracts, including Markdown-backed Codex goal prompt files and paste-sized /goal prompts, so they match the user's intent, evidence needs, constraints, completion rules, and output expectations without becoming brittle or overbuilt. Use for casual prompt-writing asks, system/agent/reviewer prompts, prompt repair, anti-heuristic refactors, and findings-first prompt audits; use $skill-authoring for skill packages.

Write, edit, refactor, or audit prompt-first agent skills so they stay simple by default, self-contained, anti-heuristic, and distinct from nearby peers. Use when a Codex, OpenClaw, OpenAI, Anthropic, or repo-local skill needs stronger intent, trigger boundaries, packaging, references, runtime metadata, or validation before shipping.

Run an ordered multi-step process inside a target repo with one clean worker per independent step, a new clean observational critic, and a Stepwise-owned diagnose-and-repair loop that resumes the exact worker, walks upstream when inputs are suspect, and repairs at root cause. Same-host roles prefer native children; external Claude, Codex, Grok, or Kimi sessions remain available when their provider, model, lifecycle, isolation, automation, or structured receipt provides a deliberate benefit. Use for named process execution with strict step ordering and evidence. Do NOT use for plan-doc implementation (arch-step), bet-and-learn optimization (goal-loop), one-shot reviews, or single-turn work.

Run a prompt-only cynical architecture review over a branch, diff, subsystem, plan-backed implementation, or code area by assuming the architecture was not intentionally designed but emerged through iteration and got cemented. Hunt for sprawl, invalid split ownership, duplicate truth, accidental abstractions, compatibility shims, flags-as-architecture, registries, adapters, state spread, wrong decomposition, and complexity not forced by the intended user experience or hard experiment requirements. Push subtraction-first architecture: delete, consolidate, move ownership, simplify boundaries, and preserve the same UX with fewer concepts and less code. Not for normal bug review, QA/test/doc review, exhaustive coverage review, completion-truth review, implementation, or proof harnesses.

Run a prompt-only cynical code review over implemented code, a diff, branch, path set, completion claim, or optional plan-backed implementation by assuming the completion story may be misleading and hunting for code reality gaps: name-only completion, split-brain owners, side doors, partial unification, stale authority paths, stopped-short user workflows, overbuilt machinery, scope contamination, fake proof receipts, and docs/status/tests that mask broken code. Use when the user asks for a skeptical, adversarial, cynical, or implementation-integrity audit of code that may look done but be subtly wrong. Not for normal review, coverage-ledger exhaustive review, plan-readiness audit, maintainability-only thermonuclear review, implementation, repair, PR shipping, or external subprocess review.

Run a prompt-only cynical cruft removal review over a repo, branch, diff, subsystem, test suite, or artifact set by assuming references are not proof of value. Produce a deep deletion report for low-value items that should go away: dead code, self-referential islands, retired V1/V2 paths, stale feature flags, worthless tests, fake coverage, unused dependencies, obsolete configs/scripts, stale generated artifacts, and point-in-time docs/examples that no longer serve a live purpose. Use when the user wants skeptical cleanup judgment and deletion candidates, not normal code review, docs-only cleanup, architecture review, implementation, or automated deletion.

Audit any planning document format before work starts, or run plan-backed implementation-audit code review after code exists. Use when the user wants a plan, PRD, migration plan, architecture plan, checklist, issue body, inline plan, or design doc audited for North Star clarity, done-state requirements, ambiguity, constraints, tiny-team simplicity, depth-first risk, elegant architecture, existing-pattern fit, drift-proofing, side doors, deletes, proof gaps, and bug-vector reduction; or wants implemented code reviewed against that plan for code shape, ownership, SSOT, side-door closure, drift, caller fit, and elegance. Not for writing plans, implementing code, generic diff/PR review, choosing workflows, running tests, proving CI, or spawning review harnesses.

Upload local artifact files or directories (HTML reports, screenshots, analysis bundles, any static files) to the team's Cloudflare R2 share bucket and return a public unguessable https://share.fun.country/<slug>/... URL. Use when the user says 'upload this to cloudflare somewhere I can share', wants a link to drop in Slack, or wants a local HTML report viewable by teammates. Requires a secret env file at ~/.config/cf-share/env (see references/setup.md). Not for deploying apps or product content (ps-content CDN), not for claude.ai Artifacts, and not for material that must stay private.

Write Markdown-backed goal prompt files for ArcStep runs from a user ask plus an optional canonical DOC_PATH, especially `$arch-step auto-plan`, `implement-loop`, `auto-implement`, or `full-auto`. Use when the user wants a durable Codex/Claude goal prompt that references source truth without copying the plan, keeps implementation aligned with plan intent, and catches surface-level completion. Not for executing ArcStep itself or creating harnesses, runners, or controllers.

Audit and score an agent-definition markdown such as `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, `SOUL.md`, `.cursorrules`, or a system prompt using a cold-reader rubric for clarity, consistency, context independence, operating-model fit, and coherent agent-dispatch semantics when present. Use when the user asks to review, score, critique, or audit an agent instruction file. Not for evaluating agent outputs, code quality, or rewriting the file itself.

Search and interpret local Codex or Claude Code session history from natural-language asks about prior prompts, goals, commands, corrections, tool use, timelines, or agent behavior. Use the current runtime, current project, and last 24h by default unless the user says otherwise. Run the bundled helpers for JSONL/SQLite extraction, then synthesize evidence with confidence notes. Do not require rigid syntax, replace Git commit history tools, launch subprocesses, or dump raw transcripts by default.

Write, edit, refactor, or audit `AGENTS.md` files for coding projects so they stay concise, repo-present, plain-English, command-first, scope-aware, and non-inferable. Use when a repo needs a new root or path-local `AGENTS.md`, an `AGENTS.override.md`, a compressed docs index, or a findings-first review of existing agent instructions.

Aggressively retire stale repo documentation with the DGTFO loop: ground every topic against current code, treat old point-in-time docs as delete candidates by default, fold durable truth into real evergreen homes, and only keep or author standalone docs when current readers genuinely need them. Use when stale worklogs, implementation docs, misleading `living` docs, outdated READMEs, dead migration notes, or explicit native goal-mode `auto` docs cleanup need a code-grounded delete-first pass. Not for generic copy editing, open-ended aspirational doc authoring, or speculative taxonomy redesign.

Create or repair a standalone one-pass mini architecture plan that writes the canonical arch blocks into one doc and then hands follow-through to `miniarch-step` or `arch-step`, with later docs cleanup handled by `arch-docs` using the finished artifact as context. Use when a request asks for a mini plan, compressed arch plan, or single-pass planning pass without running the full staged arch workflow. Not for tiny 1-3 phase features, bugs, open-ended loops, or full-arch execution.

Operate the standalone full-arch workflow against one canonical plan artifact and explicit doctrine: `new`, `reformat`, `research`, `deep-dive`, `external-research`, `phase-plan`, `auto-plan`, `plan-enhance`, `fold-in`, `overbuild-protector`, `consistency-pass`, `review-gate`, `implement`, `implement-loop`, `auto-implement`, `full-auto`, `audit-implementation`, `status`, or `advance`. Use when the user wants the full arch workflow, a specific full-arch step, or concise full-arch status. Initial architecture may include the smallest evidenced same-contract convergence closure before scope freezes; later expansion requires explicit human approval. Not for read-only checklist routing, mini plans, lilarch, bugs, or open-ended loops.

Run the standalone real-app automation audit workflow with a root simulator audit ledger: exhaustively map the app, journeys, and current automation surface before any edits, rank automation risk fronts by consequence and proof weakness, then fix the biggest end-to-end automation gaps and same-story bugs without changing contracts. Every editful pass must then audit its own diff for safety, unintended downstream consequences, elegance, and duplication before it can count as done. Use when the user wants repo-wide simulator or emulator automation work, wants the agent to build a full mental model before acting, or wants to leave the automation audit running in Codex or Claude Code until no credible work remains. Not for a single known bug, generic repo audit, or manual QA-only work.

Run the standalone repo-audit workflow with a root audit ledger: exhaustively map the codebase and current proof surface before any edits, rank risk fronts by consequence and proof weakness, then fix the biggest real bugs, dead code, duplication, and high-value regression gaps without changing contracts. Every editful pass must then audit its own diff for safety, unintended downstream consequences, elegance, and duplication before it can count as done. Use when the user wants a repo-wide audit pass, wants the agent to build a full mental model before acting, or wants to leave the audit running in Codex or Claude Code until no credible audit work remains. Not for a single known bug, feature planning, or generic optimization loops.

Run the standalone repo comment-hardening workflow with a root comment ledger: exhaustively map the repo, current proof surface, and current explanatory coverage before any edits, then add or repair only high-leverage code comments, docstrings, and doc comments for shared contracts, conventions, gotchas, and subtle behavior without changing contracts or spamming obvious narration. Use when the user wants a repo-wide code-comment pass, wants the agent to deeply understand the codebase before explaining it, or wants to leave the comment audit running in Codex or Claude Code until no credible high-impact explanation gaps remain. Not for generic docs cleanup, a one-off local comment tweak, or bug fixing.

Run a prompt-only exhaustive code review over a branch, diff, path set, plan scope, or completion claim with a coverage-led set of clean native review slices when useful, reading touched files/hunks/abstractions/callers/side doors/proof/docs/generated/prompt surfaces, and saving a findings-first review artifact to disk. Use when the user asks for exhaustive, meticulous, line-by-line, file-by-file, abstraction-by-abstraction, feature-by-feature, or coverage-ledger review. Not for normal high-signal review, plan-backed `plan-audit implementation-audit`, maintainability-only thermonuclear review, implementation, repair, PR shipping, or external subprocess review.

Run the standalone small-feature 1-3 phase flow: create or repair a compact plan doc, lock requirements and defaults, write a tight implementation plan, implement locally, and self-audit. Use when a request is a contained feature or improvement that can realistically ship in 1-3 phases. Not for full-arch work, one-pass mini plans, bug investigations, or open-ended loops.

Operate the trimmed standalone full-arch workflow against one canonical plan artifact: `new`, `reformat`, `research`, `deep-dive`, `phase-plan`, `auto-plan`, `implement`, `implement-loop`, `auto-implement`, `full-auto`, `audit-implementation`, `status`, or `advance`. Use when the work still needs canonical architecture grounding, phased execution, and native goal-mode auto flow, but does not need the broader staged surface of `arch-step`. Not for one-pass mini planning, 1-3 phase feature flow, broad or ambiguity-heavy full-arch work, bugs, or open-ended loops.

Read-only flow-status and next-step router for arch-step, miniarch-step, arch-mini-plan, and lilarch docs. Use when the user asks 'what's next?', wants a checklist, or wants the single best next move without running the workflow. Not for doing the planning or implementation work itself.

Explain the arch skill suite, distinguish the live subskills, and recommend the right one for a user's task. Use when a request asks which arch skill to use, what the difference is between `arch-step`, `miniarch-step`, `arch-docs`, `arch-mini-plan`, `lilarch`, `bugs-flow`, `audit-loop`, `comment-loop`, `audit-loop-sim`, `goal-loop`, `north-star-investigation`, `arch-flow`, or wants a quick tour of the arch suite. Not for actually running the underlying workflow.

Write and publish high-quality GitHub pull requests from real repo changes. Use when the user asks to create, open, author, update, or publish a PR, or to turn the current branch/diff into a GitHub PR body/title. This owns PR authoring plus GitHub publication; it is not for code review, release notes, changelogs, or merely printing a suggested PR description.

Explicit-invocation PR follow-through loop for an already-open GitHub pull request: poll the PR, triage every new review or comment thread with judgment, reply on-thread with accept/decline rationale, push warranted fixes to the same branch, and repeat until the PR is merge-ready.

Convert Markdown or document content into FC / Poker Skill branded PDF artifacts using the bundled letterhead CSS, logo, and local renderer. Use for reports, memos, briefs, packets, audits, summaries, exported document tabs, or any ask for an FC-branded PDF / FC letterhead PDF. Not for Drive archival, slide decks, image/video generation, or ordinary chat answers.

Author, review, or repair Figma files, component libraries, variables, handoff surfaces, and source-backed app/Figma fidelity audits using prompt-first file-craft doctrine. Use for Figma organization, components, tokens, Dev Mode/Code Connect/Make/MCP readiness, duplicate/stale cleanup, screenshot/reference handling, and app/source parity evidence. Do not use for generic visual taste critique, implementing frontend code from Figma, operating the Figma UI/tool itself, or deterministic visual-diff automation.

Rewrite the current branch's branch-span Git commit messages into an informative narrative while preserving patches and commit boundaries. Use when the user wants WIP/vague commits re-authored, branch history clarified from its nearest parent branch, or an active arch plan called out in commit bodies before sharing. Safety-first: infer the parent/base, allow the current branch's own remote ref, block unrelated shared refs, create a backup branch, never push/force-push, and do not squash/split/reorder unless explicitly asked for a separate history-editing flow. Not for PR bodies, changelogs, release notes, code review, or rewriting parent/shared history.

Use as a Flutter app-building reference for architecture, code quality, Dart style, state management, lifecycle, performance, rendering, testing, CI, accessibility, localization, security, platform integration, and Flame/game-loop guidance. Use when authoring, reviewing, repairing, or diagnosing Flutter mobile apps or games. Do not use for non-Flutter frontend work, generic visual design, running Flutter tooling, or latest Flutter/Dart facts without checking official docs.