From e0d093e5b2a9664bf23ed1f3b1c5cbb09a2064ae Mon Sep 17 00:00:00 2001 From: Daniel Howells Date: Wed, 12 Aug 2026 22:35:55 +0100 Subject: [PATCH 1/2] docs: consolidate agent instructions into AGENTS.md Single agent file: AGENTS.md, with CLAUDE.md symlinked to it. Repo-specific knowledge only - cross-cutting rules now live in the global ~/.claude/AGENTS.md. Claude-Session: https://claude.ai/code/session_01VNRqQfvanEdsgdFdSaLtti --- .claude-plugin/marketplace.json | 4 +- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- .cursor-plugin/marketplace.json | 4 +- .cursor-plugin/plugin.json | 2 +- AGENTS.md | 80 +++++++++++++++------------ CLAUDE.md | 56 +------------------ package.json | 2 +- plugins/arc/.codex-plugin/plugin.json | 2 +- 9 files changed, 56 insertions(+), 98 deletions(-) mode change 100644 => 120000 CLAUDE.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 75ee61d..c669bd6 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", - "version": "2.11.1" + "version": "2.11.3" }, "plugins": [ { "name": "arc", "source": "./", "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", - "version": "2.11.1", + "version": "2.11.3", "author": { "name": "Daniel Howells" }, diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 37db36a..ec417f3 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "arc", - "version": "2.11.1", + "version": "2.11.3", "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", "skills": "./skills/", "commands": "./commands/", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 294a854..bfce6b4 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "arc", - "version": "2.11.1", + "version": "2.11.3", "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", "author": { "name": "Daniel Howells", diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 798611d..3d8c323 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", - "version": "2.11.1" + "version": "2.11.3" }, "plugins": [ { "name": "arc", "source": "./", "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", - "version": "2.11.1", + "version": "2.11.3", "author": { "name": "Daniel Howells" }, diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 5378b62..68ea8cb 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "arc", "displayName": "Arc", - "version": "2.11.1", + "version": "2.11.3", "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", "author": { "name": "Daniel Howells" diff --git a/AGENTS.md b/AGENTS.md index 2bb774e..511b571 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,36 +1,48 @@ -# Arc Plugin - Agent Instructions - -## Communication Expectations -- State which Arc workflow or artifact you are changing before editing. -- Keep workflow explanations precise; Arc is lifecycle machinery, not generic project documentation. -- When changing command behavior, mention the matching skill, command stub, agents, references, and tests affected. - -## How To Work In This Codebase -- Read `CONTEXT.md` for product boundary and language before changing workflow behavior. -- Slash commands in `commands/` route to skills in `skills/`; do not fork behavior between them. -- Runtime support files live in `agents/`, `disciplines/`, `references/`, `rules/`, `templates/`, `scripts/`, and `tests/`. -- Site work is isolated under `site/` and uses its own Next.js scripts. - -## Editing Constraints -- Keep Arc self-contained. Do not make core workflows depend on optional external plugins or skills. -- Do not copy project-local rules into Arc unless they are general Arc runtime rules. -- When adding a required reference to a skill, make sure the referenced file exists and the skill tells agents when to read it. -- Keep generated plugin packaging files consistent with `.codex`, `.cursor-plugin`, command stubs, and skill paths. - -## Search Preferences -- Search `skills//SKILL.md` before changing command docs. -- Search `references/` and `disciplines/` before creating new methodology text. -- For path questions, use `references/arc-paths.md` as the canonical artifact-location reference. +# Arc + +The full arc from idea to shipped code, shipped as a plugin for Claude Code, Codex, and Cursor. `CONTEXT.md` is the canonical product definition, domain language, and operating boundary - read it before changing workflow behaviour. Treat this file as contributor guidance, not a competing definition. + +## Shape + +- Each skill in `skills//SKILL.md` is one `/arc:` command, routed by a thin `commands/.md`. Never fork behaviour between the two. +- Commands: `/arc:ideate`, `/arc:review`, `/arc:implement`, `/arc:testing`, `/arc:audit`, `/arc:improve`, `/arc:refactor`, `/arc:commit`, `/arc:release`, `/arc:launch`, `/arc:vision`. +- Canonical flow is `ideate -> (review) -> implement`. `audit`, `improve`, `commit`, `release`, and `refactor` are cross-cutting and available anytime. +- Skills draw on `agents/` (subagents), `references/` (domain knowledge, catalogued in `references/index.md`), `rules/`, `disciplines/` (methodologies), and `templates/` (output structures). +- `skills/using-arc/` is the session control plane; `skills/detail/` is internal to `implement`. Neither has a command router. +- Site work is isolated under `site/` with its own Next.js scripts. +- `rules/` is Arc's internal corpus, loaded selectively by workflows. It's shipped in the plugin payload but never injected as always-on Cursor rules - `tests/test-cursor-plugin.sh` enforces that. + +## Gotchas + +- **Rebuild the Codex mirror after any change to `skills/`, `agents/`, `references/`, `rules/`, `disciplines/`, `templates/`, `scripts/`, or `commands/`.** Run `pnpm build:codex`. The pre-commit hook and `tests/test-codex-mirror.sh` both fail on a stale mirror, and the failure names the diffing file rather than the real cause. +- **`plugins/arc/` is generated. Never edit it by hand** - `scripts/build-codex-plugin.sh` overwrites it wholesale. +- **Version bumps touch five manifests.** Use `bash scripts/bump-version.sh `, never a manual edit: it updates `package.json`, `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/` (plugin *and* marketplace), and the generated `plugins/arc/.codex-plugin/`. Verify with `bash scripts/bump-version.sh --check`. A post-commit hook auto-bumps the patch version and amends content commits. +- **Adding a skill needs more than a `SKILL.md`.** It also needs a `commands/.md` router, a `.agents/skills/` symlink, and entries in the plugin manifests - `tests/test-skill-loading.sh` hardcodes the expected skill list and fails on any unexpected directory. +- **Agents are not skills.** Every file in `agents/*/*.md` keeps its own `` and unconditionally loads `references/subagent-safety.md`. That's deliberate: agents are dispatched as subagents and skip `using-arc` via its `` block, so those local blocks are their only path grounding and injection defence. `tests/test-xml-tags.sh` enforces tag containment for agents but not for skills, for the same reason. +- **Skills must stay self-sufficient.** `audit`, `improve`, and `refactor` carry `context: fork` and run isolated; command routers also invoke skills cold. Don't centralise a skill's `` into `using-arc` - path resolution would silently break. +- Adding a required reference to a skill means the file must exist and the skill must say when to read it. `tests/test-agents-and-refs.sh` checks the first half. + +## Editing constraints + +- Keep Arc self-contained. Core workflows must not depend on optional external plugins or skills. +- Don't copy project-local rules into Arc unless they're general Arc runtime rules. +- Mastra may be reviewed by Arc agents, but Arc itself must not become a Mastra runtime. +- When changing command behaviour, name the matching skill, command stub, agents, references, and tests affected. + +## Search order + +- `skills//SKILL.md` before changing command docs. +- `references/` and `disciplines/` before writing new methodology text. +- `references/arc-paths.md` is the canonical artifact-location reference. ## Commands -- `pnpm test` - run skill tests. -- `pnpm lint` / `pnpm lint:fix` / `pnpm format` - shared lint and format lanes. -- `pnpm build:codex` - build Codex plugin package. -- `pnpm dev` - run the documentation site from `site/`. -- `pnpm --dir site typecheck` - site TypeScript check. - -## Repo-Specific Rules -- Canonical Arc flow: vision, ideate, review, implement, testing, launch, with audit, refactor, and commit as cross-cutting workflows. -- Small workflow edits still need verification against command routing and tests. -- Prefer concise operational instructions over broad coaching prose. -- Mastra may be reviewed by Arc agents, but Arc itself should not become a Mastra runtime. + +- `pnpm test` - the bash suite in `tests/`. Run before committing. +- `pnpm lint` / `pnpm lint:fix` / `pnpm format` +- `pnpm build:codex` - build the Codex plugin package. +- `pnpm dev` - documentation site from `site/`. +- `pnpm --dir site typecheck` + +## Publishing + +Bump the version, run `pnpm build:codex`, commit and push. Users update via `claude plugins update`, `codex plugin marketplace upgrade`, or `git -C ~/.cursor/plugins/local/arc pull`. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index f0f4c8a..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,55 +0,0 @@ -# Arc Plugin - -The full arc from idea to shipped code. Arc's canonical product definition, domain language, and -operating boundary live in `CONTEXT.md` — treat this file as contributor guidance, not a competing -definition. - -Each skill in `skills//SKILL.md` is one `/arc:` command, routed by a thin -`commands/.md`. Skills draw on `agents/` (subagents), `references/` (domain knowledge, -catalogued in `references/index.md`), `rules/`, `disciplines/` (methodologies), and `templates/` -(output structures). `skills/using-arc/` is the session control plane; `skills/detail/` is -internal to `implement`. Neither has a command router. - -The canonical flow is `ideate → (review) → implement`. `audit`, `improve`, `commit`, `release`, -and `refactor` are cross-cutting and available anytime. - -## Gotchas - -**The Codex mirror must be rebuilt after any change to `skills/`, `agents/`, `references/`, -`rules/`, `disciplines/`, `templates/`, `scripts/`, or `commands/`.** Run `pnpm build:codex`. The -pre-commit hook and `tests/test-codex-mirror.sh` both fail on a stale mirror, and the failure -message names the diffing file rather than the real cause. - -**`plugins/arc/` is generated. Never edit it by hand** — `scripts/build-codex-plugin.sh` overwrites -it wholesale. - -**Version bumps touch five manifests.** Use `bash scripts/bump-version.sh `, never a -manual edit: it updates `package.json`, `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/` -(plugin *and* marketplace), and the generated `plugins/arc/.codex-plugin/`. Verify with -`bash scripts/bump-version.sh --check`. A post-commit hook auto-bumps the patch version and amends -content commits. - -**Adding a skill needs more than a `SKILL.md`.** It also needs a `commands/.md` router, a -`.agents/skills/` symlink, and entries in the plugin manifests — `tests/test-skill-loading.sh` -hardcodes the expected skill list and fails on any unexpected directory. - -**Agents are not skills.** All 25 files in `agents/*/*.md` keep their own `` and -unconditionally load `references/subagent-safety.md`. That is deliberate: agents are dispatched as -subagents and skip `using-arc` via its `` block, so those local blocks are their -only path grounding and injection defence. `tests/test-xml-tags.sh` enforces tag containment for -agents but not for skills, for the same reason. - -**Skills must stay self-sufficient.** `audit`, `improve`, and `refactor` carry `context: fork` and -run isolated; command routers also invoke skills cold. Don't centralise a skill's `` -into `using-arc` — path resolution would silently break. - -## Development - -Edit the skill, run the command, iterate. Run `pnpm test` (the bash suite in `tests/`) before -committing. - -## Publishing - -Bump the version, run `pnpm build:codex`, commit and push. Users update via -`claude plugins update`, `codex plugin marketplace upgrade`, or -`git -C ~/.cursor/plugins/local/arc pull`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/package.json b/package.json index cdcaa85..8c5812d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "arc-plugin", - "version": "2.11.1", + "version": "2.11.3", "private": true, "description": "Arc workflows for Claude Code and Codex", "scripts": { diff --git a/plugins/arc/.codex-plugin/plugin.json b/plugins/arc/.codex-plugin/plugin.json index 294a854..bfce6b4 100644 --- a/plugins/arc/.codex-plugin/plugin.json +++ b/plugins/arc/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "arc", - "version": "2.11.1", + "version": "2.11.3", "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", "author": { "name": "Daniel Howells", From 61f551a7f11d6ed7db1fce0e242a8582eb071acc Mon Sep 17 00:00:00 2001 From: Daniel Howells Date: Fri, 14 Aug 2026 13:27:40 +0100 Subject: [PATCH 2/2] docs: deprecate Arc in favour of focused skills --- .claude-plugin/marketplace.json | 8 +- .claude-plugin/plugin.json | 4 +- .codex-plugin/plugin.json | 15 +-- .cursor-plugin/marketplace.json | 8 +- .cursor-plugin/plugin.json | 4 +- CONTEXT.md | 2 + README.md | 3 + package.json | 2 +- plugins/arc/.codex-plugin/plugin.json | 15 +-- plugins/arc/CONTEXT.md | 2 + plugins/arc/references/audit-detection.md | 20 +-- .../arc/references/audit-reviewer-prompts.md | 2 - plugins/arc/references/audit-scorecard.md | 4 +- plugins/arc/references/audit-signals.md | 15 ++- .../arc/references/audit-stage-calibration.md | 2 +- plugins/arc/references/index.md | 118 +++++++++--------- plugins/arc/references/plan-lifecycle.md | 10 +- plugins/arc/references/review-patterns.md | 2 +- plugins/arc/references/testing-patterns.md | 2 +- plugins/arc/skills/audit/SKILL.md | 14 +-- plugins/arc/skills/implement/SKILL.md | 16 +-- plugins/arc/skills/launch/SKILL.md | 16 +-- references/audit-detection.md | 20 +-- references/audit-reviewer-prompts.md | 2 - references/audit-scorecard.md | 4 +- references/audit-signals.md | 15 ++- references/audit-stage-calibration.md | 2 +- references/index.md | 118 +++++++++--------- references/plan-lifecycle.md | 10 +- references/review-patterns.md | 2 +- references/testing-patterns.md | 2 +- site/src/app/layout.tsx | 26 +++- site/src/app/llms.txt/route.ts | 2 + site/src/app/page.tsx | 4 +- skills/audit/SKILL.md | 14 +-- skills/implement/SKILL.md | 16 +-- skills/launch/SKILL.md | 16 +-- 37 files changed, 272 insertions(+), 265 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c669bd6..5df421e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -4,15 +4,15 @@ "name": "Daniel Howells" }, "metadata": { - "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", - "version": "2.11.3" + "description": "Deprecated and no longer maintained. Arc remains available as an archive; use github.com/howells/skills for focused agent skills.", + "version": "2.11.4" }, "plugins": [ { "name": "arc", "source": "./", - "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", - "version": "2.11.3", + "description": "Deprecated and no longer maintained. Arc remains available as an archive; use github.com/howells/skills for focused agent skills.", + "version": "2.11.4", "author": { "name": "Daniel Howells" }, diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ec417f3..6f28b7d 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "arc", - "version": "2.11.3", - "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", + "version": "2.11.4", + "description": "Deprecated and no longer maintained. Arc remains available as an archive; use github.com/howells/skills for focused agent skills.", "skills": "./skills/", "commands": "./commands/", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index bfce6b4..274ab79 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "arc", - "version": "2.11.3", - "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", + "version": "2.11.4", + "description": "Deprecated and no longer maintained. Arc remains available as an archive; use github.com/howells/skills for focused agent skills.", "author": { "name": "Daniel Howells", "url": "https://github.com/howells" @@ -25,19 +25,14 @@ "skills": "./skills/", "interface": { "displayName": "Arc", - "shortDescription": "Software development lifecycle workflows", - "longDescription": "Arc packages a self-contained software development lifecycle for coding agents, from vision and ideation through implementation, testing, review, audit, launch readiness, and commit hygiene.", + "shortDescription": "Deprecated lifecycle workflow archive", + "longDescription": "Arc is deprecated and no longer maintained. It remains available as an archive for existing users. For maintained, focused agent skills, use https://github.com/howells/skills.", "developerName": "Daniel Howells", "category": "Productivity", "capabilities": [ "Interactive", "Write" ], - "websiteURL": "https://usearc.dev", - "defaultPrompt": [ - "Use Arc to turn this idea into shipped code.", - "Use Arc to audit this codebase.", - "Use Arc to prepare this project for launch." - ] + "websiteURL": "https://usearc.dev" } } diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 3d8c323..a780c55 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -4,15 +4,15 @@ "name": "Daniel Howells" }, "metadata": { - "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", - "version": "2.11.3" + "description": "Deprecated and no longer maintained. Arc remains available as an archive; use github.com/howells/skills for focused agent skills.", + "version": "2.11.4" }, "plugins": [ { "name": "arc", "source": "./", - "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", - "version": "2.11.3", + "description": "Deprecated and no longer maintained. Arc remains available as an archive; use github.com/howells/skills for focused agent skills.", + "version": "2.11.4", "author": { "name": "Daniel Howells" }, diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 68ea8cb..084e3cc 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "arc", "displayName": "Arc", - "version": "2.11.3", - "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", + "version": "2.11.4", + "description": "Deprecated and no longer maintained. Arc remains available as an archive; use github.com/howells/skills for focused agent skills.", "author": { "name": "Daniel Howells" }, diff --git a/CONTEXT.md b/CONTEXT.md index ff986fb..2edb097 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,5 +1,7 @@ # Arc Context +> **Deprecated:** Arc is preserved as an archive and remains available, but it is no longer maintained. Maintained, focused agent skills live in [Howells Skills](https://github.com/howells/skills). + This is the canonical source for Arc's product definition, domain language, and operating boundary. README, agent instructions, website copy, and individual skills may summarize Arc, but they should not introduce competing definitions. Arc is a self-contained software development lifecycle for coding agents. It helps move work from idea to shipped code through explicit workflows for vision, ideation, implementation, review, testing, launch readiness, commit hygiene, and versioned package releases when a change includes a publishable package. diff --git a/README.md b/README.md index e4044d0..0295c9e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,6 @@ +> [!IMPORTANT] +> **Arc is deprecated and no longer maintained.** It remains available as an archive, but I won't be updating it. For maintained, focused agent skills, use [Howells Skills](https://github.com/howells/skills). +

Arc Arc diff --git a/package.json b/package.json index 8c5812d..3d47831 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "arc-plugin", - "version": "2.11.3", + "version": "2.11.4", "private": true, "description": "Arc workflows for Claude Code and Codex", "scripts": { diff --git a/plugins/arc/.codex-plugin/plugin.json b/plugins/arc/.codex-plugin/plugin.json index bfce6b4..274ab79 100644 --- a/plugins/arc/.codex-plugin/plugin.json +++ b/plugins/arc/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "arc", - "version": "2.11.3", - "description": "The full arc from idea to shipped code. Lifecycle workflows for vision, ideation, implementation, review, testing, audit, launch, and commits.", + "version": "2.11.4", + "description": "Deprecated and no longer maintained. Arc remains available as an archive; use github.com/howells/skills for focused agent skills.", "author": { "name": "Daniel Howells", "url": "https://github.com/howells" @@ -25,19 +25,14 @@ "skills": "./skills/", "interface": { "displayName": "Arc", - "shortDescription": "Software development lifecycle workflows", - "longDescription": "Arc packages a self-contained software development lifecycle for coding agents, from vision and ideation through implementation, testing, review, audit, launch readiness, and commit hygiene.", + "shortDescription": "Deprecated lifecycle workflow archive", + "longDescription": "Arc is deprecated and no longer maintained. It remains available as an archive for existing users. For maintained, focused agent skills, use https://github.com/howells/skills.", "developerName": "Daniel Howells", "category": "Productivity", "capabilities": [ "Interactive", "Write" ], - "websiteURL": "https://usearc.dev", - "defaultPrompt": [ - "Use Arc to turn this idea into shipped code.", - "Use Arc to audit this codebase.", - "Use Arc to prepare this project for launch." - ] + "websiteURL": "https://usearc.dev" } } diff --git a/plugins/arc/CONTEXT.md b/plugins/arc/CONTEXT.md index ff986fb..2edb097 100644 --- a/plugins/arc/CONTEXT.md +++ b/plugins/arc/CONTEXT.md @@ -1,5 +1,7 @@ # Arc Context +> **Deprecated:** Arc is preserved as an archive and remains available, but it is no longer maintained. Maintained, focused agent skills live in [Howells Skills](https://github.com/howells/skills). + This is the canonical source for Arc's product definition, domain language, and operating boundary. README, agent instructions, website copy, and individual skills may summarize Arc, but they should not introduce competing definitions. Arc is a self-contained software development lifecycle for coding agents. It helps move work from idea to shipped code through explicit workflows for vision, ideation, implementation, review, testing, launch readiness, commit hygiene, and versioned package releases when a change includes a publishable package. diff --git a/plugins/arc/references/audit-detection.md b/plugins/arc/references/audit-detection.md index a62f246..08eb081 100644 --- a/plugins/arc/references/audit-detection.md +++ b/plugins/arc/references/audit-detection.md @@ -28,17 +28,17 @@ find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" Infer the project stage from heuristic signals: -| Signal | Tool | Indicates | -| ---------------------------------------------------------------------------------- | ------------------------------------ | --------------- | -| CI/CD config (`.github/workflows/*`, `Jenkinsfile`, `.gitlab-ci.yml`) | Glob | pre-launch+ | -| Deployment config (`vercel.json`, `Dockerfile`, `fly.toml`, `render.yaml`, `k8s/`) | Glob | pre-launch+ | -| Monitoring/observability (`sentry`, `datadog`, `newrelic` in deps) | Grep in package.json | production | -| Production env references (`.env.production`, `NODE_ENV` guards) | Glob + Grep | pre-launch+ | -| Test coverage > 0 (test files exist) | Glob (`**/*.test.*`, `**/*.spec.*`) | development+ | -| Git history depth | `git rev-list --count HEAD` | maturity signal | +| Signal | Tool | Indicates | +| ---------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------- | +| CI/CD config (`.github/workflows/*`, `Jenkinsfile`, `.gitlab-ci.yml`) | Glob | pre-launch+ | +| Deployment config (`vercel.json`, `Dockerfile`, `fly.toml`, `render.yaml`, `k8s/`) | Glob | pre-launch+ | +| Monitoring/observability (`sentry`, `datadog`, `newrelic` in deps) | Grep in package.json | production | +| Production env references (`.env.production`, `NODE_ENV` guards) | Glob + Grep | pre-launch+ | +| Test coverage > 0 (test files exist) | Glob (`**/*.test.*`, `**/*.spec.*`) | development+ | +| Git history depth | `git rev-list --count HEAD` | maturity signal | | Not a git repository (command errors) | `git rev-parse --git-dir` | treat as unknown, not as shallow history — do not count it toward `prototype` | -| Custom domain / production URL in config | Grep | production | -| Rate limiting, caching, or queue deps in package.json | Grep (`rate-limit`, `redis`, `bull`) | production | +| Custom domain / production URL in config | Grep | production | +| Rate limiting, caching, or queue deps in package.json | Grep (`rate-limit`, `redis`, `bull`) | production | **Stage classification:** diff --git a/plugins/arc/references/audit-reviewer-prompts.md b/plugins/arc/references/audit-reviewer-prompts.md index 7e71a1c..2789efb 100644 --- a/plugins/arc/references/audit-reviewer-prompts.md +++ b/plugins/arc/references/audit-reviewer-prompts.md @@ -59,7 +59,6 @@ Focus on: N+1 queries, missing indexes, memory leaks, bundle size, render perfor ``` - --- ## What Every Reviewer Prompt Carries @@ -67,7 +66,6 @@ Focus on: N+1 queries, missing indexes, memory leaks, bundle size, render perfor Context to pass at dispatch, and the per-reviewer emphasis that makes each manifest actionable in that reviewer's domain. - **Include project stage in every reviewer prompt.** Each reviewer must receive the stage context so they can calibrate their severity ratings. Read the matching stage calibration block from: diff --git a/plugins/arc/references/audit-scorecard.md b/plugins/arc/references/audit-scorecard.md index 8d4ed45..8e9c0f4 100644 --- a/plugins/arc/references/audit-scorecard.md +++ b/plugins/arc/references/audit-scorecard.md @@ -60,7 +60,7 @@ Is the codebase organized for change? | Score | Criteria | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | God files (authored source 1000+ LOC, or any file 2000+ LOC), god page-clients (thin page/layout passing through to one giant `"use client"` component), circular dependencies, barrel files, cross-workspace app imports, business logic tangled with UI | -| 1 | Some structure but boundaries are leaky — mixed concerns, server/client boundary hacks (`*-wrapper`, `*-client`, client boundaries hoisted too high), files in the 600–999 LOC band, deep coupling between modules | +| 1 | Some structure but boundaries are leaky — mixed concerns, server/client boundary hacks (`*-wrapper`, `*-client`, client boundaries hoisted too high), files in the 600–999 LOC band, deep coupling between modules | | 2 | Clear module boundaries and proper server/client split. Some areas of high coupling or unclear ownership remain | | 3 | Clean separation of concerns, well-defined interfaces, dependency direction enforced. Adding features doesn't require touching unrelated code | @@ -72,7 +72,7 @@ Is the code readable, correct, and maintainable? | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 0 | No type safety or `any` throughout, no linting, dead code everywhere, inconsistent patterns | | 1 | Types exist but gaps — some `any`/casts, lint warnings, direct `process.env` reads with no typed env strategy, useless barrel files, runtime `import()`, inconsistent naming, dead exports | -| 2 | Strong types, lint-clean, env via a typed strategy, no useless barrels, consistent patterns, minimal dead code. Some files in the 600–999 LOC band | +| 2 | Strong types, lint-clean, env via a typed strategy, no useless barrels, consistent patterns, minimal dead code. Some files in the 600–999 LOC band | | 3 | Strict types throughout, zero lint issues, no file over the 600 LOC ceiling, no barrel/dynamic-import smells, consistent patterns, no dead code, complexity under control | ### 5. Test Health diff --git a/plugins/arc/references/audit-signals.md b/plugins/arc/references/audit-signals.md index 6bb0287..db5e6da 100644 --- a/plugins/arc/references/audit-signals.md +++ b/plugins/arc/references/audit-signals.md @@ -108,13 +108,13 @@ with one job is fine, and a 300-line file doing four things is not. Bands are non-overlapping and a boundary count belongs to the higher band — a 1000-line file is Severe. Thresholds are inclusive everywhere these numbers appear: 600+, 1000+, 2000+. -| Band | How hard to look | -| ---- | ---------------- | -| ≤ 300 LOC | Normal. No attention needed on size alone. | -| 301–599 LOC | Hotspot. Confirm one coherent responsibility. | -| 600–999 LOC | Presumptive god file. Read it; expect to justify keeping it whole. | -| 1000–1999 LOC | Severe. Near-certain god file — say so unless the code refutes it. | -| 2000+ LOC | Strongest signal available. Default finding is "split this"; argue the exception in the writeup if the file earns it. | +| Band | How hard to look | +| ------------- | --------------------------------------------------------------------------------------------------------------------- | +| ≤ 300 LOC | Normal. No attention needed on size alone. | +| 301–599 LOC | Hotspot. Confirm one coherent responsibility. | +| 600–999 LOC | Presumptive god file. Read it; expect to justify keeping it whole. | +| 1000–1999 LOC | Severe. Near-certain god file — say so unless the code refutes it. | +| 2000+ LOC | Strongest signal available. Default finding is "split this"; argue the exception in the writeup if the file earns it. | Standing exemptions at every band: generated, vendored, data-only, or a structure the codebase demonstrably needs. @@ -236,4 +236,3 @@ python3 scripts/codebase-map.py ${scope:-.} --format markdown If it succeeds, store the output as the **codebase map manifest**. If it fails or the script is unavailable in a prompt-only install, record `Codebase map: unavailable` and continue with the existing detection passes. Treat the map as orientation, not evidence by itself. Reviewers must still inspect files before reporting findings. - diff --git a/plugins/arc/references/audit-stage-calibration.md b/plugins/arc/references/audit-stage-calibration.md index 3ba9ec2..46a09b6 100644 --- a/plugins/arc/references/audit-stage-calibration.md +++ b/plugins/arc/references/audit-stage-calibration.md @@ -69,7 +69,7 @@ Use during consolidation to sanity-check reviewer findings: | Missing tests | Drop | Low | Medium | High | | Credential exposure | Critical | Critical | Critical | Critical | | SQL injection / XSS | Critical | Critical | Critical | Critical | -| Architecture concerns | Drop* | Low | Medium | High | +| Architecture concerns | Drop\* | Low | Medium | High | | Performance optimization | Drop | Low | Medium | High | | Accessibility gaps | Drop | Low | Medium | High | diff --git a/plugins/arc/references/index.md b/plugins/arc/references/index.md index 72c7a6d..515b51d 100644 --- a/plugins/arc/references/index.md +++ b/plugins/arc/references/index.md @@ -8,82 +8,82 @@ you need background and can't name the file. ## Workflow & Planning -| Reference | Use when | -|-----------|----------| -| [arc-paths.md](arc-paths.md) | Deciding where an Arc artifact belongs on disk | -| [plan-lifecycle.md](plan-lifecycle.md) | Managing plan status, resumption, and the plan index | -| [task-granularity.md](task-granularity.md) | Sizing tasks and writing plan XML | -| [implementation-assurance.md](implementation-assurance.md) | Choosing an assurance tier and verification receipt | -| [checkpoint-patterns.md](checkpoint-patterns.md) | Placing checkpoints in a long execution | -| [question-loops.md](question-loops.md) | Running a one-question-at-a-time interview | -| [platform-tools.md](platform-tools.md) | Mapping Claude tool names onto Codex or Cursor | +| Reference | Use when | +| ---------------------------------------------------------- | ---------------------------------------------------- | +| [arc-paths.md](arc-paths.md) | Deciding where an Arc artifact belongs on disk | +| [plan-lifecycle.md](plan-lifecycle.md) | Managing plan status, resumption, and the plan index | +| [task-granularity.md](task-granularity.md) | Sizing tasks and writing plan XML | +| [implementation-assurance.md](implementation-assurance.md) | Choosing an assurance tier and verification receipt | +| [checkpoint-patterns.md](checkpoint-patterns.md) | Placing checkpoints in a long execution | +| [question-loops.md](question-loops.md) | Running a one-question-at-a-time interview | +| [platform-tools.md](platform-tools.md) | Mapping Claude tool names onto Codex or Cursor | ## Review & Audit -| Reference | Use when | -|-----------|----------| -| [audit-scorecard.md](audit-scorecard.md) | Scoring the 7 codebase-health axes | -| [audit-stage-calibration.md](audit-stage-calibration.md) | Calibrating severity to project stage | -| [audit-detection.md](audit-detection.md) | Detecting project scale, lifecycle stage, and the security gate | -| [audit-signals.md](audit-signals.md) | Running the Phase 1 mechanical scan passes | -| [audit-reviewer-rules.md](audit-reviewer-rules.md) | Choosing which coding rules each reviewer receives | -| [audit-reviewer-prompts.md](audit-reviewer-prompts.md) | Composing reviewer dispatch prompts | -| [finding-vetting.md](finding-vetting.md) | Confirming a finding before reporting it | -| [maintainability-review.md](maintainability-review.md) | Judging structural code health and file size | -| [code-smells.md](code-smells.md) | Establishing a shared review baseline | -| [diff-review-checklist.md](diff-review-checklist.md) | Reviewing a diff before it lands | -| [review-patterns.md](review-patterns.md) | Turning findings into Socratic questions | -| [complexity-optimization.md](complexity-optimization.md) | Ranking algorithmic improvements by impact | -| [verification-patterns.md](verification-patterns.md) | Detecting stubs and placeholder implementations | -| [launch-scorecard.md](launch-scorecard.md) | Scoring go-live readiness | -| [operations-playbook.md](operations-playbook.md) | Remediating CI, env, and alerting gaps | +| Reference | Use when | +| -------------------------------------------------------- | --------------------------------------------------------------- | +| [audit-scorecard.md](audit-scorecard.md) | Scoring the 7 codebase-health axes | +| [audit-stage-calibration.md](audit-stage-calibration.md) | Calibrating severity to project stage | +| [audit-detection.md](audit-detection.md) | Detecting project scale, lifecycle stage, and the security gate | +| [audit-signals.md](audit-signals.md) | Running the Phase 1 mechanical scan passes | +| [audit-reviewer-rules.md](audit-reviewer-rules.md) | Choosing which coding rules each reviewer receives | +| [audit-reviewer-prompts.md](audit-reviewer-prompts.md) | Composing reviewer dispatch prompts | +| [finding-vetting.md](finding-vetting.md) | Confirming a finding before reporting it | +| [maintainability-review.md](maintainability-review.md) | Judging structural code health and file size | +| [code-smells.md](code-smells.md) | Establishing a shared review baseline | +| [diff-review-checklist.md](diff-review-checklist.md) | Reviewing a diff before it lands | +| [review-patterns.md](review-patterns.md) | Turning findings into Socratic questions | +| [complexity-optimization.md](complexity-optimization.md) | Ranking algorithmic improvements by impact | +| [verification-patterns.md](verification-patterns.md) | Detecting stubs and placeholder implementations | +| [launch-scorecard.md](launch-scorecard.md) | Scoring go-live readiness | +| [operations-playbook.md](operations-playbook.md) | Remediating CI, env, and alerting gaps | ## Architecture & Frontend -| Reference | Use when | -|-----------|----------| -| [architecture-patterns.md](architecture-patterns.md) | Judging module boundaries and system shape | -| [component-design.md](component-design.md) | Designing React component APIs | -| [react-audit-signals.md](react-audit-signals.md) | Inspecting React/Next.js hotspots during audit | -| [nextjs-app-router.md](nextjs-app-router.md) | Working with App Router, RSC, and server-first patterns | -| [tanstack-query-trpc.md](tanstack-query-trpc.md) | Wiring TanStack Query or tRPC data flow | -| [tanstack-table.md](tanstack-table.md) | Building data tables with TanStack Table v8 | -| [prefetch-patterns.md](prefetch-patterns.md) | Tuning navigation prefetch and perceived speed | -| [authentication.md](authentication.md) | Implementing auth flows (Clerk, WorkOS, sessions) | -| [database-lifecycle.md](database-lifecycle.md) | Judging migrations, journals, and backup posture | +| Reference | Use when | +| ---------------------------------------------------- | ------------------------------------------------------- | +| [architecture-patterns.md](architecture-patterns.md) | Judging module boundaries and system shape | +| [component-design.md](component-design.md) | Designing React component APIs | +| [react-audit-signals.md](react-audit-signals.md) | Inspecting React/Next.js hotspots during audit | +| [nextjs-app-router.md](nextjs-app-router.md) | Working with App Router, RSC, and server-first patterns | +| [tanstack-query-trpc.md](tanstack-query-trpc.md) | Wiring TanStack Query or tRPC data flow | +| [tanstack-table.md](tanstack-table.md) | Building data tables with TanStack Table v8 | +| [prefetch-patterns.md](prefetch-patterns.md) | Tuning navigation prefetch and perceived speed | +| [authentication.md](authentication.md) | Implementing auth flows (Clerk, WorkOS, sessions) | +| [database-lifecycle.md](database-lifecycle.md) | Judging migrations, journals, and backup posture | ## Design & Interface -| Reference | Use when | -|-----------|----------| -| [design-philosophy.md](design-philosophy.md) | Establishing timeless visual direction | -| [frontend-design.md](frontend-design.md) | Applying the component checklist and anti-patterns | -| [ux-laws.md](ux-laws.md) | Reasoning about Fitts, Hick, and friends | -| [interaction-physics.md](interaction-physics.md) | Tuning motion feel, easing, and responsiveness | -| [animation-patterns.md](animation-patterns.md) | Implementing deeper animation and motion systems | -| [typography-opentype.md](typography-opentype.md) | Setting type scale and OpenType features | -| [touch-targets.md](touch-targets.md) | Sizing hit areas for touch and pointer input | -| [ascii-ui-patterns.md](ascii-ui-patterns.md) | Sketching layout as ASCII wireframes during design | -| [tailwind-v4.md](tailwind-v4.md) | Migrating to or authoring for Tailwind v4 | +| Reference | Use when | +| ------------------------------------------------ | -------------------------------------------------- | +| [design-philosophy.md](design-philosophy.md) | Establishing timeless visual direction | +| [frontend-design.md](frontend-design.md) | Applying the component checklist and anti-patterns | +| [ux-laws.md](ux-laws.md) | Reasoning about Fitts, Hick, and friends | +| [interaction-physics.md](interaction-physics.md) | Tuning motion feel, easing, and responsiveness | +| [animation-patterns.md](animation-patterns.md) | Implementing deeper animation and motion systems | +| [typography-opentype.md](typography-opentype.md) | Setting type scale and OpenType features | +| [touch-targets.md](touch-targets.md) | Sizing hit areas for touch and pointer input | +| [ascii-ui-patterns.md](ascii-ui-patterns.md) | Sketching layout as ASCII wireframes during design | +| [tailwind-v4.md](tailwind-v4.md) | Migrating to or authoring for Tailwind v4 | See also `rules/interface/index.md` for the enforceable interface rules these references sit behind. ## Testing -| Reference | Use when | -|-----------|----------| -| [testing-patterns.md](testing-patterns.md) | Choosing test shape and evidence | +| Reference | Use when | +| ---------------------------------------------------- | -------------------------------------------- | +| [testing-patterns.md](testing-patterns.md) | Choosing test shape and evidence | | [testing-anti-patterns.md](testing-anti-patterns.md) | Diagnosing tests that pass but catch nothing | -| [llm-api-testing.md](llm-api-testing.md) | Testing code that calls an LLM API | +| [llm-api-testing.md](llm-api-testing.md) | Testing code that calls an LLM API | ## Agents & Delegation -| Reference | Use when | -|-----------|----------| -| [subagent-safety.md](subagent-safety.md) | Dispatching any subagent (prompt-injection defence) | -| [subagent-statuses.md](subagent-statuses.md) | Interpreting and propagating subagent status | -| [model-strategy.md](model-strategy.md) | Choosing a model tier per agent | -| [agent-teams.md](agent-teams.md) | Composing a team with fallback behaviour | -| [agent-evals.md](agent-evals.md) | Building golden sets and evals for agents | +| Reference | Use when | +| -------------------------------------------- | --------------------------------------------------- | +| [subagent-safety.md](subagent-safety.md) | Dispatching any subagent (prompt-injection defence) | +| [subagent-statuses.md](subagent-statuses.md) | Interpreting and propagating subagent status | +| [model-strategy.md](model-strategy.md) | Choosing a model tier per agent | +| [agent-teams.md](agent-teams.md) | Composing a team with fallback behaviour | +| [agent-evals.md](agent-evals.md) | Building golden sets and evals for agents | Disciplines (methodologies rather than domain knowledge) live in `disciplines/`. diff --git a/plugins/arc/references/plan-lifecycle.md b/plugins/arc/references/plan-lifecycle.md index fe08dcd..c853516 100644 --- a/plugins/arc/references/plan-lifecycle.md +++ b/plugins/arc/references/plan-lifecycle.md @@ -26,12 +26,12 @@ dependency notes. A required section once anything has been rejected. It is what stops a dismissed finding resurfacing every time a new report is read, so it must survive as long as the index does. -| Column | Content | -| -------- | ----------------------------------------------------------- | +| Column | Content | +| -------- | ------------------------------------------------------------- | | Finding | One-line description, enough to recognise a restatement of it | -| Evidence | `file:line` as originally cited | -| Reason | Why it was rejected — by design, already fixed, not worth it | -| Date | When the verdict was recorded | +| Evidence | `file:line` as originally cited | +| Reason | Why it was rejected — by design, already fixed, not worth it | +| Date | When the verdict was recorded | Match new findings against this ledger before planning them. A finding that reappears with materially new evidence may be reopened; note that in the Reason column rather than deleting the row. diff --git a/plugins/arc/references/review-patterns.md b/plugins/arc/references/review-patterns.md index 860d706..ca78388 100644 --- a/plugins/arc/references/review-patterns.md +++ b/plugins/arc/references/review-patterns.md @@ -98,7 +98,7 @@ If user says "I'm not sure, but I think we need it": - Present reviewer feedback as mandates - Use "should" or "must" for simplification suggestions - Make the user defend their choices -- Batch all feedback at the end of a *conversational* design review (present as you go). A +- Batch all feedback at the end of a _conversational_ design review (present as you go). A consolidated panel review — independent reviewers, then one merged pass — is a different shape and legitimately presents after collection. - Assume reviewers are right and user is wrong diff --git a/plugins/arc/references/testing-patterns.md b/plugins/arc/references/testing-patterns.md index 53ec787..8cb9822 100644 --- a/plugins/arc/references/testing-patterns.md +++ b/plugins/arc/references/testing-patterns.md @@ -27,7 +27,7 @@ public or architectural boundary. New plans register seams using the XML contrac | `behavior` | Write an assertion at an agreed seam, watch it fail for the missing behavior, implement, then watch it pass. | | `bugfix` | Reproduce the defect at the seam, verify the expected failure, fix it, then keep the regression green. | | `integration` | Use observable contract/integration evidence at a named seam. Require red only when local behavior changes and a meaningful pre-change failure can be demonstrated. Otherwise record the baseline and targeted passing evidence. | -| `refactor` | Run affected tests before and after. Add characterization coverage only where behavior lacks a safety net (see the proportionality note below). | +| `refactor` | Run affected tests before and after. Add characterization coverage only where behavior lacks a safety net (see the proportionality note below). | | `artifact` | Use build, package, generation, schema, or mechanical verification. | | `deployment` | Use authorized read-only smoke evidence. External mutation still requires authority. | | `documentation` | Use content and link validation where applicable. | diff --git a/plugins/arc/skills/audit/SKILL.md b/plugins/arc/skills/audit/SKILL.md index 79d6f41..6557ec0 100644 --- a/plugins/arc/skills/audit/SKILL.md +++ b/plugins/arc/skills/audit/SKILL.md @@ -59,13 +59,13 @@ Where native task tracking exists, check for an existing task for this audit and Load each at the phase that needs it, not up front: -| Phase | Load | -| ----- | ---- | -| 1 — detect | `references/audit-detection.md`, `references/audit-signals.md` | -| 3 — dispatch | `references/audit-reviewer-rules.md`, `references/audit-reviewer-prompts.md`, `disciplines/dispatching-parallel-agents.md`, `references/maintainability-review.md` | -| 3 and 4 — score and calibrate | `references/audit-scorecard.md`, `references/audit-stage-calibration.md` | -| 4 — vet | `references/finding-vetting.md` | -| 5 — report | `templates/audit-report.md` | +| Phase | Load | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 — detect | `references/audit-detection.md`, `references/audit-signals.md` | +| 3 — dispatch | `references/audit-reviewer-rules.md`, `references/audit-reviewer-prompts.md`, `disciplines/dispatching-parallel-agents.md`, `references/maintainability-review.md` | +| 3 and 4 — score and calibrate | `references/audit-scorecard.md`, `references/audit-stage-calibration.md` | +| 4 — vet | `references/finding-vetting.md` | +| 5 — report | `templates/audit-report.md` | Load when relevant: diff --git a/plugins/arc/skills/implement/SKILL.md b/plugins/arc/skills/implement/SKILL.md index 48197df..42d9d99 100644 --- a/plugins/arc/skills/implement/SKILL.md +++ b/plugins/arc/skills/implement/SKILL.md @@ -64,14 +64,14 @@ Load when relevant: -| Agent | Default use | -| ---------------------------------------------------------------- | -------------------------------------------------------------------------- | -| `agents/build/implementer.md` | Own a coherent implementation slice end-to-end. | -| `unit-test-writer`, `integration-test-writer`, `e2e-test-writer` | **Conditional** complex harness, fixture, browser/E2E, or test-suite work. | -| `debugger`, `fixer` | An observed failing test, typecheck, or lint result. | -| `test-runner`, `e2e-runner` | Verbose or iterative focused execution when useful. | -| `agents/build/spec-reviewer.md` | Sonnet whole-implementation spec/completion axis. | -| `agents/build/code-reviewer.md` | Sonnet whole-implementation standards/evidence axis. | +| Agent | Default use | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| `agents/build/implementer.md` | Own a coherent implementation slice end-to-end. | +| `unit-test-writer`, `integration-test-writer`, `e2e-test-writer` | **Conditional** complex harness, fixture, browser/E2E, or test-suite work. | +| `debugger`, `fixer` | An observed failing test, typecheck, or lint result. | +| `test-runner`, `e2e-runner` | Verbose or iterative focused execution when useful. | +| `agents/build/spec-reviewer.md` | Sonnet whole-implementation spec/completion axis. | +| `agents/build/code-reviewer.md` | Sonnet whole-implementation standards/evidence axis. | | `agents/review/security-engineer.md`, `agents/review/data-engineer.md`, `agents/review/performance-engineer.md`, `agents/review/mastra-agent-engineer.md`, `agents/review/daniel-product-engineer.md`, `agents/review/accessibility-engineer.md` | **Conditional** Guarded specialists, matched to the risk that raised assurance. | All build agents live in `agents/build/`; specialists in `agents/review/`. Read an agent file before dispatching it. Never run multiple mutating owners in parallel when diff --git a/plugins/arc/skills/launch/SKILL.md b/plugins/arc/skills/launch/SKILL.md index 076ad9b..eb72043 100644 --- a/plugins/arc/skills/launch/SKILL.md +++ b/plugins/arc/skills/launch/SKILL.md @@ -234,14 +234,14 @@ Use this shape: ```markdown ## Launch Scorecard -| Axis | Score | Evidence | -| ----------------- | :------: | ---------------------------------------------------------------- | -| Public URL | X/3 | [verified URL/DNS/HTTPS/access-gate evidence or gap] | -| Shareability | X/3 | [metadata, OG image, favicon, canonical, robots evidence or gap] | -| Content Readiness | X/3 | [placeholder/CTA/contact/error-state evidence or gap] | -| Detected Services | X/3 | [auth/payment/email/db/analytics public-setting evidence or gap] | -| Deeper Checks | X/3 | [`/arc:testing` and `/arc:audit` status or deferral] | -| **Total** | **X/15** | **Ready / Ready, with operations caveats / Shareable with caveats / Blocked** | +| Axis | Score | Evidence | +| ----------------- | :------: | ----------------------------------------------------------------------------- | +| Public URL | X/3 | [verified URL/DNS/HTTPS/access-gate evidence or gap] | +| Shareability | X/3 | [metadata, OG image, favicon, canonical, robots evidence or gap] | +| Content Readiness | X/3 | [placeholder/CTA/contact/error-state evidence or gap] | +| Detected Services | X/3 | [auth/payment/email/db/analytics public-setting evidence or gap] | +| Deeper Checks | X/3 | [`/arc:testing` and `/arc:audit` status or deferral] | +| **Total** | **X/15** | **Ready / Ready, with operations caveats / Shareable with caveats / Blocked** | ``` ## Output diff --git a/references/audit-detection.md b/references/audit-detection.md index a62f246..08eb081 100644 --- a/references/audit-detection.md +++ b/references/audit-detection.md @@ -28,17 +28,17 @@ find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" Infer the project stage from heuristic signals: -| Signal | Tool | Indicates | -| ---------------------------------------------------------------------------------- | ------------------------------------ | --------------- | -| CI/CD config (`.github/workflows/*`, `Jenkinsfile`, `.gitlab-ci.yml`) | Glob | pre-launch+ | -| Deployment config (`vercel.json`, `Dockerfile`, `fly.toml`, `render.yaml`, `k8s/`) | Glob | pre-launch+ | -| Monitoring/observability (`sentry`, `datadog`, `newrelic` in deps) | Grep in package.json | production | -| Production env references (`.env.production`, `NODE_ENV` guards) | Glob + Grep | pre-launch+ | -| Test coverage > 0 (test files exist) | Glob (`**/*.test.*`, `**/*.spec.*`) | development+ | -| Git history depth | `git rev-list --count HEAD` | maturity signal | +| Signal | Tool | Indicates | +| ---------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------- | +| CI/CD config (`.github/workflows/*`, `Jenkinsfile`, `.gitlab-ci.yml`) | Glob | pre-launch+ | +| Deployment config (`vercel.json`, `Dockerfile`, `fly.toml`, `render.yaml`, `k8s/`) | Glob | pre-launch+ | +| Monitoring/observability (`sentry`, `datadog`, `newrelic` in deps) | Grep in package.json | production | +| Production env references (`.env.production`, `NODE_ENV` guards) | Glob + Grep | pre-launch+ | +| Test coverage > 0 (test files exist) | Glob (`**/*.test.*`, `**/*.spec.*`) | development+ | +| Git history depth | `git rev-list --count HEAD` | maturity signal | | Not a git repository (command errors) | `git rev-parse --git-dir` | treat as unknown, not as shallow history — do not count it toward `prototype` | -| Custom domain / production URL in config | Grep | production | -| Rate limiting, caching, or queue deps in package.json | Grep (`rate-limit`, `redis`, `bull`) | production | +| Custom domain / production URL in config | Grep | production | +| Rate limiting, caching, or queue deps in package.json | Grep (`rate-limit`, `redis`, `bull`) | production | **Stage classification:** diff --git a/references/audit-reviewer-prompts.md b/references/audit-reviewer-prompts.md index 7e71a1c..2789efb 100644 --- a/references/audit-reviewer-prompts.md +++ b/references/audit-reviewer-prompts.md @@ -59,7 +59,6 @@ Focus on: N+1 queries, missing indexes, memory leaks, bundle size, render perfor ``` - --- ## What Every Reviewer Prompt Carries @@ -67,7 +66,6 @@ Focus on: N+1 queries, missing indexes, memory leaks, bundle size, render perfor Context to pass at dispatch, and the per-reviewer emphasis that makes each manifest actionable in that reviewer's domain. - **Include project stage in every reviewer prompt.** Each reviewer must receive the stage context so they can calibrate their severity ratings. Read the matching stage calibration block from: diff --git a/references/audit-scorecard.md b/references/audit-scorecard.md index 8d4ed45..8e9c0f4 100644 --- a/references/audit-scorecard.md +++ b/references/audit-scorecard.md @@ -60,7 +60,7 @@ Is the codebase organized for change? | Score | Criteria | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | God files (authored source 1000+ LOC, or any file 2000+ LOC), god page-clients (thin page/layout passing through to one giant `"use client"` component), circular dependencies, barrel files, cross-workspace app imports, business logic tangled with UI | -| 1 | Some structure but boundaries are leaky — mixed concerns, server/client boundary hacks (`*-wrapper`, `*-client`, client boundaries hoisted too high), files in the 600–999 LOC band, deep coupling between modules | +| 1 | Some structure but boundaries are leaky — mixed concerns, server/client boundary hacks (`*-wrapper`, `*-client`, client boundaries hoisted too high), files in the 600–999 LOC band, deep coupling between modules | | 2 | Clear module boundaries and proper server/client split. Some areas of high coupling or unclear ownership remain | | 3 | Clean separation of concerns, well-defined interfaces, dependency direction enforced. Adding features doesn't require touching unrelated code | @@ -72,7 +72,7 @@ Is the code readable, correct, and maintainable? | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 0 | No type safety or `any` throughout, no linting, dead code everywhere, inconsistent patterns | | 1 | Types exist but gaps — some `any`/casts, lint warnings, direct `process.env` reads with no typed env strategy, useless barrel files, runtime `import()`, inconsistent naming, dead exports | -| 2 | Strong types, lint-clean, env via a typed strategy, no useless barrels, consistent patterns, minimal dead code. Some files in the 600–999 LOC band | +| 2 | Strong types, lint-clean, env via a typed strategy, no useless barrels, consistent patterns, minimal dead code. Some files in the 600–999 LOC band | | 3 | Strict types throughout, zero lint issues, no file over the 600 LOC ceiling, no barrel/dynamic-import smells, consistent patterns, no dead code, complexity under control | ### 5. Test Health diff --git a/references/audit-signals.md b/references/audit-signals.md index 6bb0287..db5e6da 100644 --- a/references/audit-signals.md +++ b/references/audit-signals.md @@ -108,13 +108,13 @@ with one job is fine, and a 300-line file doing four things is not. Bands are non-overlapping and a boundary count belongs to the higher band — a 1000-line file is Severe. Thresholds are inclusive everywhere these numbers appear: 600+, 1000+, 2000+. -| Band | How hard to look | -| ---- | ---------------- | -| ≤ 300 LOC | Normal. No attention needed on size alone. | -| 301–599 LOC | Hotspot. Confirm one coherent responsibility. | -| 600–999 LOC | Presumptive god file. Read it; expect to justify keeping it whole. | -| 1000–1999 LOC | Severe. Near-certain god file — say so unless the code refutes it. | -| 2000+ LOC | Strongest signal available. Default finding is "split this"; argue the exception in the writeup if the file earns it. | +| Band | How hard to look | +| ------------- | --------------------------------------------------------------------------------------------------------------------- | +| ≤ 300 LOC | Normal. No attention needed on size alone. | +| 301–599 LOC | Hotspot. Confirm one coherent responsibility. | +| 600–999 LOC | Presumptive god file. Read it; expect to justify keeping it whole. | +| 1000–1999 LOC | Severe. Near-certain god file — say so unless the code refutes it. | +| 2000+ LOC | Strongest signal available. Default finding is "split this"; argue the exception in the writeup if the file earns it. | Standing exemptions at every band: generated, vendored, data-only, or a structure the codebase demonstrably needs. @@ -236,4 +236,3 @@ python3 scripts/codebase-map.py ${scope:-.} --format markdown If it succeeds, store the output as the **codebase map manifest**. If it fails or the script is unavailable in a prompt-only install, record `Codebase map: unavailable` and continue with the existing detection passes. Treat the map as orientation, not evidence by itself. Reviewers must still inspect files before reporting findings. - diff --git a/references/audit-stage-calibration.md b/references/audit-stage-calibration.md index 3ba9ec2..46a09b6 100644 --- a/references/audit-stage-calibration.md +++ b/references/audit-stage-calibration.md @@ -69,7 +69,7 @@ Use during consolidation to sanity-check reviewer findings: | Missing tests | Drop | Low | Medium | High | | Credential exposure | Critical | Critical | Critical | Critical | | SQL injection / XSS | Critical | Critical | Critical | Critical | -| Architecture concerns | Drop* | Low | Medium | High | +| Architecture concerns | Drop\* | Low | Medium | High | | Performance optimization | Drop | Low | Medium | High | | Accessibility gaps | Drop | Low | Medium | High | diff --git a/references/index.md b/references/index.md index 72c7a6d..515b51d 100644 --- a/references/index.md +++ b/references/index.md @@ -8,82 +8,82 @@ you need background and can't name the file. ## Workflow & Planning -| Reference | Use when | -|-----------|----------| -| [arc-paths.md](arc-paths.md) | Deciding where an Arc artifact belongs on disk | -| [plan-lifecycle.md](plan-lifecycle.md) | Managing plan status, resumption, and the plan index | -| [task-granularity.md](task-granularity.md) | Sizing tasks and writing plan XML | -| [implementation-assurance.md](implementation-assurance.md) | Choosing an assurance tier and verification receipt | -| [checkpoint-patterns.md](checkpoint-patterns.md) | Placing checkpoints in a long execution | -| [question-loops.md](question-loops.md) | Running a one-question-at-a-time interview | -| [platform-tools.md](platform-tools.md) | Mapping Claude tool names onto Codex or Cursor | +| Reference | Use when | +| ---------------------------------------------------------- | ---------------------------------------------------- | +| [arc-paths.md](arc-paths.md) | Deciding where an Arc artifact belongs on disk | +| [plan-lifecycle.md](plan-lifecycle.md) | Managing plan status, resumption, and the plan index | +| [task-granularity.md](task-granularity.md) | Sizing tasks and writing plan XML | +| [implementation-assurance.md](implementation-assurance.md) | Choosing an assurance tier and verification receipt | +| [checkpoint-patterns.md](checkpoint-patterns.md) | Placing checkpoints in a long execution | +| [question-loops.md](question-loops.md) | Running a one-question-at-a-time interview | +| [platform-tools.md](platform-tools.md) | Mapping Claude tool names onto Codex or Cursor | ## Review & Audit -| Reference | Use when | -|-----------|----------| -| [audit-scorecard.md](audit-scorecard.md) | Scoring the 7 codebase-health axes | -| [audit-stage-calibration.md](audit-stage-calibration.md) | Calibrating severity to project stage | -| [audit-detection.md](audit-detection.md) | Detecting project scale, lifecycle stage, and the security gate | -| [audit-signals.md](audit-signals.md) | Running the Phase 1 mechanical scan passes | -| [audit-reviewer-rules.md](audit-reviewer-rules.md) | Choosing which coding rules each reviewer receives | -| [audit-reviewer-prompts.md](audit-reviewer-prompts.md) | Composing reviewer dispatch prompts | -| [finding-vetting.md](finding-vetting.md) | Confirming a finding before reporting it | -| [maintainability-review.md](maintainability-review.md) | Judging structural code health and file size | -| [code-smells.md](code-smells.md) | Establishing a shared review baseline | -| [diff-review-checklist.md](diff-review-checklist.md) | Reviewing a diff before it lands | -| [review-patterns.md](review-patterns.md) | Turning findings into Socratic questions | -| [complexity-optimization.md](complexity-optimization.md) | Ranking algorithmic improvements by impact | -| [verification-patterns.md](verification-patterns.md) | Detecting stubs and placeholder implementations | -| [launch-scorecard.md](launch-scorecard.md) | Scoring go-live readiness | -| [operations-playbook.md](operations-playbook.md) | Remediating CI, env, and alerting gaps | +| Reference | Use when | +| -------------------------------------------------------- | --------------------------------------------------------------- | +| [audit-scorecard.md](audit-scorecard.md) | Scoring the 7 codebase-health axes | +| [audit-stage-calibration.md](audit-stage-calibration.md) | Calibrating severity to project stage | +| [audit-detection.md](audit-detection.md) | Detecting project scale, lifecycle stage, and the security gate | +| [audit-signals.md](audit-signals.md) | Running the Phase 1 mechanical scan passes | +| [audit-reviewer-rules.md](audit-reviewer-rules.md) | Choosing which coding rules each reviewer receives | +| [audit-reviewer-prompts.md](audit-reviewer-prompts.md) | Composing reviewer dispatch prompts | +| [finding-vetting.md](finding-vetting.md) | Confirming a finding before reporting it | +| [maintainability-review.md](maintainability-review.md) | Judging structural code health and file size | +| [code-smells.md](code-smells.md) | Establishing a shared review baseline | +| [diff-review-checklist.md](diff-review-checklist.md) | Reviewing a diff before it lands | +| [review-patterns.md](review-patterns.md) | Turning findings into Socratic questions | +| [complexity-optimization.md](complexity-optimization.md) | Ranking algorithmic improvements by impact | +| [verification-patterns.md](verification-patterns.md) | Detecting stubs and placeholder implementations | +| [launch-scorecard.md](launch-scorecard.md) | Scoring go-live readiness | +| [operations-playbook.md](operations-playbook.md) | Remediating CI, env, and alerting gaps | ## Architecture & Frontend -| Reference | Use when | -|-----------|----------| -| [architecture-patterns.md](architecture-patterns.md) | Judging module boundaries and system shape | -| [component-design.md](component-design.md) | Designing React component APIs | -| [react-audit-signals.md](react-audit-signals.md) | Inspecting React/Next.js hotspots during audit | -| [nextjs-app-router.md](nextjs-app-router.md) | Working with App Router, RSC, and server-first patterns | -| [tanstack-query-trpc.md](tanstack-query-trpc.md) | Wiring TanStack Query or tRPC data flow | -| [tanstack-table.md](tanstack-table.md) | Building data tables with TanStack Table v8 | -| [prefetch-patterns.md](prefetch-patterns.md) | Tuning navigation prefetch and perceived speed | -| [authentication.md](authentication.md) | Implementing auth flows (Clerk, WorkOS, sessions) | -| [database-lifecycle.md](database-lifecycle.md) | Judging migrations, journals, and backup posture | +| Reference | Use when | +| ---------------------------------------------------- | ------------------------------------------------------- | +| [architecture-patterns.md](architecture-patterns.md) | Judging module boundaries and system shape | +| [component-design.md](component-design.md) | Designing React component APIs | +| [react-audit-signals.md](react-audit-signals.md) | Inspecting React/Next.js hotspots during audit | +| [nextjs-app-router.md](nextjs-app-router.md) | Working with App Router, RSC, and server-first patterns | +| [tanstack-query-trpc.md](tanstack-query-trpc.md) | Wiring TanStack Query or tRPC data flow | +| [tanstack-table.md](tanstack-table.md) | Building data tables with TanStack Table v8 | +| [prefetch-patterns.md](prefetch-patterns.md) | Tuning navigation prefetch and perceived speed | +| [authentication.md](authentication.md) | Implementing auth flows (Clerk, WorkOS, sessions) | +| [database-lifecycle.md](database-lifecycle.md) | Judging migrations, journals, and backup posture | ## Design & Interface -| Reference | Use when | -|-----------|----------| -| [design-philosophy.md](design-philosophy.md) | Establishing timeless visual direction | -| [frontend-design.md](frontend-design.md) | Applying the component checklist and anti-patterns | -| [ux-laws.md](ux-laws.md) | Reasoning about Fitts, Hick, and friends | -| [interaction-physics.md](interaction-physics.md) | Tuning motion feel, easing, and responsiveness | -| [animation-patterns.md](animation-patterns.md) | Implementing deeper animation and motion systems | -| [typography-opentype.md](typography-opentype.md) | Setting type scale and OpenType features | -| [touch-targets.md](touch-targets.md) | Sizing hit areas for touch and pointer input | -| [ascii-ui-patterns.md](ascii-ui-patterns.md) | Sketching layout as ASCII wireframes during design | -| [tailwind-v4.md](tailwind-v4.md) | Migrating to or authoring for Tailwind v4 | +| Reference | Use when | +| ------------------------------------------------ | -------------------------------------------------- | +| [design-philosophy.md](design-philosophy.md) | Establishing timeless visual direction | +| [frontend-design.md](frontend-design.md) | Applying the component checklist and anti-patterns | +| [ux-laws.md](ux-laws.md) | Reasoning about Fitts, Hick, and friends | +| [interaction-physics.md](interaction-physics.md) | Tuning motion feel, easing, and responsiveness | +| [animation-patterns.md](animation-patterns.md) | Implementing deeper animation and motion systems | +| [typography-opentype.md](typography-opentype.md) | Setting type scale and OpenType features | +| [touch-targets.md](touch-targets.md) | Sizing hit areas for touch and pointer input | +| [ascii-ui-patterns.md](ascii-ui-patterns.md) | Sketching layout as ASCII wireframes during design | +| [tailwind-v4.md](tailwind-v4.md) | Migrating to or authoring for Tailwind v4 | See also `rules/interface/index.md` for the enforceable interface rules these references sit behind. ## Testing -| Reference | Use when | -|-----------|----------| -| [testing-patterns.md](testing-patterns.md) | Choosing test shape and evidence | +| Reference | Use when | +| ---------------------------------------------------- | -------------------------------------------- | +| [testing-patterns.md](testing-patterns.md) | Choosing test shape and evidence | | [testing-anti-patterns.md](testing-anti-patterns.md) | Diagnosing tests that pass but catch nothing | -| [llm-api-testing.md](llm-api-testing.md) | Testing code that calls an LLM API | +| [llm-api-testing.md](llm-api-testing.md) | Testing code that calls an LLM API | ## Agents & Delegation -| Reference | Use when | -|-----------|----------| -| [subagent-safety.md](subagent-safety.md) | Dispatching any subagent (prompt-injection defence) | -| [subagent-statuses.md](subagent-statuses.md) | Interpreting and propagating subagent status | -| [model-strategy.md](model-strategy.md) | Choosing a model tier per agent | -| [agent-teams.md](agent-teams.md) | Composing a team with fallback behaviour | -| [agent-evals.md](agent-evals.md) | Building golden sets and evals for agents | +| Reference | Use when | +| -------------------------------------------- | --------------------------------------------------- | +| [subagent-safety.md](subagent-safety.md) | Dispatching any subagent (prompt-injection defence) | +| [subagent-statuses.md](subagent-statuses.md) | Interpreting and propagating subagent status | +| [model-strategy.md](model-strategy.md) | Choosing a model tier per agent | +| [agent-teams.md](agent-teams.md) | Composing a team with fallback behaviour | +| [agent-evals.md](agent-evals.md) | Building golden sets and evals for agents | Disciplines (methodologies rather than domain knowledge) live in `disciplines/`. diff --git a/references/plan-lifecycle.md b/references/plan-lifecycle.md index fe08dcd..c853516 100644 --- a/references/plan-lifecycle.md +++ b/references/plan-lifecycle.md @@ -26,12 +26,12 @@ dependency notes. A required section once anything has been rejected. It is what stops a dismissed finding resurfacing every time a new report is read, so it must survive as long as the index does. -| Column | Content | -| -------- | ----------------------------------------------------------- | +| Column | Content | +| -------- | ------------------------------------------------------------- | | Finding | One-line description, enough to recognise a restatement of it | -| Evidence | `file:line` as originally cited | -| Reason | Why it was rejected — by design, already fixed, not worth it | -| Date | When the verdict was recorded | +| Evidence | `file:line` as originally cited | +| Reason | Why it was rejected — by design, already fixed, not worth it | +| Date | When the verdict was recorded | Match new findings against this ledger before planning them. A finding that reappears with materially new evidence may be reopened; note that in the Reason column rather than deleting the row. diff --git a/references/review-patterns.md b/references/review-patterns.md index 860d706..ca78388 100644 --- a/references/review-patterns.md +++ b/references/review-patterns.md @@ -98,7 +98,7 @@ If user says "I'm not sure, but I think we need it": - Present reviewer feedback as mandates - Use "should" or "must" for simplification suggestions - Make the user defend their choices -- Batch all feedback at the end of a *conversational* design review (present as you go). A +- Batch all feedback at the end of a _conversational_ design review (present as you go). A consolidated panel review — independent reviewers, then one merged pass — is a different shape and legitimately presents after collection. - Assume reviewers are right and user is wrong diff --git a/references/testing-patterns.md b/references/testing-patterns.md index 53ec787..8cb9822 100644 --- a/references/testing-patterns.md +++ b/references/testing-patterns.md @@ -27,7 +27,7 @@ public or architectural boundary. New plans register seams using the XML contrac | `behavior` | Write an assertion at an agreed seam, watch it fail for the missing behavior, implement, then watch it pass. | | `bugfix` | Reproduce the defect at the seam, verify the expected failure, fix it, then keep the regression green. | | `integration` | Use observable contract/integration evidence at a named seam. Require red only when local behavior changes and a meaningful pre-change failure can be demonstrated. Otherwise record the baseline and targeted passing evidence. | -| `refactor` | Run affected tests before and after. Add characterization coverage only where behavior lacks a safety net (see the proportionality note below). | +| `refactor` | Run affected tests before and after. Add characterization coverage only where behavior lacks a safety net (see the proportionality note below). | | `artifact` | Use build, package, generation, schema, or mechanical verification. | | `deployment` | Use authorized read-only smoke evidence. External mutation still requires authority. | | `documentation` | Use content and link validation where applicable. | diff --git a/site/src/app/layout.tsx b/site/src/app/layout.tsx index b30928d..161a07f 100644 --- a/site/src/app/layout.tsx +++ b/site/src/app/layout.tsx @@ -6,24 +6,24 @@ import { mono, sans } from "@/lib/fonts"; export const metadata: Metadata = { description: - "A software development workflow for Claude Code, Codex, and Cursor. Commands and agents that handle vision, ideation, implementation, testing, review, refactoring, audit, launch, and commit.", + "Arc is a deprecated software development workflow archive. For maintained, focused agent skills, use Howells Skills.", metadataBase: new URL("https://usearc.dev"), openGraph: { description: - "A software development workflow for Claude Code, Codex, and Cursor. Commands and agents that handle vision, ideation, implementation, testing, review, refactoring, audit, launch, and commit.", + "Arc is a deprecated software development workflow archive. For maintained, focused agent skills, use Howells Skills.", locale: "en_US", siteName: "Arc", - title: "Arc – The full arc from idea to shipped code", + title: "Arc – Deprecated workflow archive", type: "website", url: "https://usearc.dev", }, - title: "Arc – The full arc from idea to shipped code", + title: "Arc – Deprecated workflow archive", twitter: { card: "summary_large_image", creator: "@howells", description: - "A software development workflow for Claude Code, Codex, and Cursor. Commands and agents that handle vision, ideation, implementation, testing, review, refactoring, audit, launch, and commit.", - title: "Arc – The full arc from idea to shipped code", + "Arc is a deprecated software development workflow archive. For maintained, focused agent skills, use Howells Skills.", + title: "Arc – Deprecated workflow archive", }, }; @@ -34,6 +34,20 @@ export default function RootLayout({ children }: { children: ReactNode }) { lang="en" > +

{children} diff --git a/site/src/app/llms.txt/route.ts b/site/src/app/llms.txt/route.ts index 757453a..07afbeb 100644 --- a/site/src/app/llms.txt/route.ts +++ b/site/src/app/llms.txt/route.ts @@ -9,6 +9,8 @@ export function GET() { const lines = [ "# Arc", "", + "> DEPRECATED: Arc is preserved as an archive and remains available, but it is no longer maintained. Use https://github.com/howells/skills for maintained, focused agent skills.", + "", `> The full arc from idea to shipped code. For Claude Code, Codex, and Cursor, with ${skills.length} skills, ${agents.length} agents, and ${rules.length} rules.${version !== null && version !== "" ? ` v${version}.` : ""}`, "", "## Skills", diff --git a/site/src/app/page.tsx b/site/src/app/page.tsx index d8935ab..42fbe73 100644 --- a/site/src/app/page.tsx +++ b/site/src/app/page.tsx @@ -17,8 +17,8 @@ import { PageContent } from "./page-content"; export const metadata: Metadata = { alternates: { canonical: "/" }, description: - "A software development workflow for Claude Code, Codex, and Cursor. Commands and agents that handle vision, ideation, implementation, testing, review, refactoring, audit, launch, and commit.", - title: "Arc – The full arc from idea to shipped code", + "Arc is a deprecated software development workflow archive. For maintained, focused agent skills, use Howells Skills.", + title: "Arc – Deprecated workflow archive", }; function TopNav({ version }: { version: string | null }) { diff --git a/skills/audit/SKILL.md b/skills/audit/SKILL.md index 79d6f41..6557ec0 100644 --- a/skills/audit/SKILL.md +++ b/skills/audit/SKILL.md @@ -59,13 +59,13 @@ Where native task tracking exists, check for an existing task for this audit and Load each at the phase that needs it, not up front: -| Phase | Load | -| ----- | ---- | -| 1 — detect | `references/audit-detection.md`, `references/audit-signals.md` | -| 3 — dispatch | `references/audit-reviewer-rules.md`, `references/audit-reviewer-prompts.md`, `disciplines/dispatching-parallel-agents.md`, `references/maintainability-review.md` | -| 3 and 4 — score and calibrate | `references/audit-scorecard.md`, `references/audit-stage-calibration.md` | -| 4 — vet | `references/finding-vetting.md` | -| 5 — report | `templates/audit-report.md` | +| Phase | Load | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 — detect | `references/audit-detection.md`, `references/audit-signals.md` | +| 3 — dispatch | `references/audit-reviewer-rules.md`, `references/audit-reviewer-prompts.md`, `disciplines/dispatching-parallel-agents.md`, `references/maintainability-review.md` | +| 3 and 4 — score and calibrate | `references/audit-scorecard.md`, `references/audit-stage-calibration.md` | +| 4 — vet | `references/finding-vetting.md` | +| 5 — report | `templates/audit-report.md` | Load when relevant: diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 48197df..42d9d99 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -64,14 +64,14 @@ Load when relevant: -| Agent | Default use | -| ---------------------------------------------------------------- | -------------------------------------------------------------------------- | -| `agents/build/implementer.md` | Own a coherent implementation slice end-to-end. | -| `unit-test-writer`, `integration-test-writer`, `e2e-test-writer` | **Conditional** complex harness, fixture, browser/E2E, or test-suite work. | -| `debugger`, `fixer` | An observed failing test, typecheck, or lint result. | -| `test-runner`, `e2e-runner` | Verbose or iterative focused execution when useful. | -| `agents/build/spec-reviewer.md` | Sonnet whole-implementation spec/completion axis. | -| `agents/build/code-reviewer.md` | Sonnet whole-implementation standards/evidence axis. | +| Agent | Default use | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| `agents/build/implementer.md` | Own a coherent implementation slice end-to-end. | +| `unit-test-writer`, `integration-test-writer`, `e2e-test-writer` | **Conditional** complex harness, fixture, browser/E2E, or test-suite work. | +| `debugger`, `fixer` | An observed failing test, typecheck, or lint result. | +| `test-runner`, `e2e-runner` | Verbose or iterative focused execution when useful. | +| `agents/build/spec-reviewer.md` | Sonnet whole-implementation spec/completion axis. | +| `agents/build/code-reviewer.md` | Sonnet whole-implementation standards/evidence axis. | | `agents/review/security-engineer.md`, `agents/review/data-engineer.md`, `agents/review/performance-engineer.md`, `agents/review/mastra-agent-engineer.md`, `agents/review/daniel-product-engineer.md`, `agents/review/accessibility-engineer.md` | **Conditional** Guarded specialists, matched to the risk that raised assurance. | All build agents live in `agents/build/`; specialists in `agents/review/`. Read an agent file before dispatching it. Never run multiple mutating owners in parallel when diff --git a/skills/launch/SKILL.md b/skills/launch/SKILL.md index 076ad9b..eb72043 100644 --- a/skills/launch/SKILL.md +++ b/skills/launch/SKILL.md @@ -234,14 +234,14 @@ Use this shape: ```markdown ## Launch Scorecard -| Axis | Score | Evidence | -| ----------------- | :------: | ---------------------------------------------------------------- | -| Public URL | X/3 | [verified URL/DNS/HTTPS/access-gate evidence or gap] | -| Shareability | X/3 | [metadata, OG image, favicon, canonical, robots evidence or gap] | -| Content Readiness | X/3 | [placeholder/CTA/contact/error-state evidence or gap] | -| Detected Services | X/3 | [auth/payment/email/db/analytics public-setting evidence or gap] | -| Deeper Checks | X/3 | [`/arc:testing` and `/arc:audit` status or deferral] | -| **Total** | **X/15** | **Ready / Ready, with operations caveats / Shareable with caveats / Blocked** | +| Axis | Score | Evidence | +| ----------------- | :------: | ----------------------------------------------------------------------------- | +| Public URL | X/3 | [verified URL/DNS/HTTPS/access-gate evidence or gap] | +| Shareability | X/3 | [metadata, OG image, favicon, canonical, robots evidence or gap] | +| Content Readiness | X/3 | [placeholder/CTA/contact/error-state evidence or gap] | +| Detected Services | X/3 | [auth/payment/email/db/analytics public-setting evidence or gap] | +| Deeper Checks | X/3 | [`/arc:testing` and `/arc:audit` status or deferral] | +| **Total** | **X/15** | **Ready / Ready, with operations caveats / Shareable with caveats / Blocked** | ``` ## Output