⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
document
Record a decision, document existing code, or file a supplied research material. Modes: document decision (ADR, RFC, or rule), document code (spec, doc, guide, or scenario for existing behavior), document research (only when a finished report or one external material is already in hand). Use for 'we decided', 'record this decision', 'document why we chose X', 'make it our standard', 'draft an RFC', 'should we switch to Y' proposals, 'resolve the RFC', 'we accepted the proposal', 'document the auth module', 'capture how the payment system works', reference material, how-to instructions, or a user flow with examples over an existing spec. Name the type inside the subject to skip the type question. Planning a feature or an intended user journey → /archcore:plan. Checking docs against code or docs health → /archcore:review.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
Archcore
Git-native project context for AI coding agents.The agent stops guessing and starts following the system.
Website · Docs · Quick start
Install · Three commands · What you get · How it compares · Go deeper
curl -fsSL https://archcore.ai/install.sh | bash
A coding agent can write the code. It does not know your project: what the feature must do, where the code belongs, and which decisions and rules already apply. So it guesses, and you explain the same things again in the next session.
Archcore keeps specs, decisions, rules, and plans in Git, next to the code. Your agent reads them before it changes the code, so the change fits your architecture and past decisions.
Ask your agent in plain words:
- "Plan rate limiting for the public API."
- "Record why we chose Redis for the token bucket."
- "Document how the billing module works."
- "Review my branch before merge."
The agent picks the document type, asks only what it cannot find in the repo, and writes plain Markdown into .archcore/.
Install
1. Install the CLI and the agent plugins.
On macOS, Linux, or WSL:
curl -fsSL https://archcore.ai/install.sh | bash
On Windows (PowerShell 5.1+):
irm https://archcore.ai/install.ps1 | iex
The installer adds the CLI. It also adds the plugins for Claude Code, Codex CLI, GitHub Copilot CLI, and OpenCode when it finds them.
2. Connect your project.
archcore init
archcore init connects the agents you choose to this project.
3. Start in your agent.
/archcore:init
/archcore:init reads the repo and proposes a first set of documents: the stack, how to run the project, and an architecture overview. You confirm once.
Say /archcore:init import in your agent. Archcore turns those files into typed project documents.
| Agent | Setup |
|---|---|
| Claude Code, Codex CLI, GitHub Copilot CLI | The installer adds the plugin |
| OpenCode | archcore init adds the plugin to the global OpenCode config, or run opencode plugin add @archcore/opencode-plugin. Details |
| Gemini CLI, Roo Code, Cline | archcore init connects them |
| Cursor | One extra setup step |
The documents stay in your repo, in .archcore/. Details: privacy.
Three commands
| When | Command | What you get |
|---|---|---|
| Before you build | /archcore:plan [your feature] | A spec, examples, and tasks, sized to the change |
| As you go | /archcore:document [subject] | One sentence from you becomes a finished, linked document |
| Before merge | /archcore:review | The branch checked against the documents, with the side that is wrong |
Use the three commands together on one change, or use one alone. The slash commands run in Claude Code, Cursor, Codex CLI, and GitHub Copilot. In OpenCode, they are /archcore-plan, /archcore-document, and /archcore-review. In every connected agent, a plain sentence works too.
Plan: the agent builds from documents, not from a chat message
/archcore:plan [your feature]
/archcore:plan reads the repo and the existing documents first. Then it asks you only what it cannot find there. You never choose a template or a mode: plan creates only the documents that the change needs.
| The change | What plan prepares |
|---|---|
| A small fix | No documents |
| A settled choice | A decision record |
| A change to existing behavior | A check of the covering spec: update the spec, or fix the code |
| A sequenced migration | A plan |
| One new capability | A spec and a plan |
| Several capabilities | A PRD, one spec per capability, and a plan |
A user-facing change also gets examples in Given/When/Then form. A risk adds the check it needs: a security fix gets a security check. A formal requirements chain starts only when an obligation asks for traceability. A data migration that people run by hand adds a migration runbook. Larger work can add a PRD or research.
The agent then implements from the spec, the examples, and the tasks. The open questions are settled before the code, not after it.
Document: you say it once, Archcore writes the document
/archcore:document why we chose [X]
/archcore:document how [module] works
/archcore:document records what is true now: a decision, a team standard, how a module works, or a how-to. Archcore selects the document type, reads the code, and checks that the document does not exist yet. It links the new document to the related ones.
With no subject, /archcore:document reads the changes on your branch and asks one question about what to record.
A decision can also produce the rule and the guide that follow from it. Each document has a status (draft, then accepted), and review checks it against the code.
Review: the code and the documents agree before merge
/archcore:review
When documents cover the change, /archcore:review compares the branch with them in both directions. Each finding names the code and the document that disagree, and carries one verdict:
code-wrong: the code breaks a document that still stands. Fix the code.spec-wrong: the document is out of date. Fix the document.
When a plan covers the branch, review checks its tasks and closes the plan when the work is done.
When no document covers the change, review still checks the branch against the decisions and rules the project has. If the branch repeats a pattern that no document records, review offers to record it. To record work that shipped without a plan, run /archcore:document.
What you get
Each command leaves plain Markdown in .archcore/, versioned with the code it describes. The document type is in the filename.
.archcore/
├── architecture/
│ └── architecture-overview.doc.md ← /archcore:init
├── conventions/
│ └── project-stack.rule.md ← /archcore:init
└── api/
├── rate-limiting.spec.md ← /archcore:plan
├── rate-limiting.plan.md ← /archcore:plan
├── token-bucket-in-redis.adr.md ← /archcore:document
└── error-shapes.rule.md ← /archcore:document
A change to a document is a diff in a pull request, like a change to code. This repository's own .archcore/ is a working example.
How it compares
| | Chat history | One CLAUDE.md or AGENTS.md | Archco
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
plugins/archcore/skills/document/SKILL.md7.9 KBupstream ↗
--- name: document argument-hint: "[decision|code|research] [subject]" description: "Record a decision, document existing code, or file a supplied research material. Modes: document decision (ADR, RFC, or rule), document code (spec, doc, guide, or scenario for existing behavior), document research (only when a finished report or one external material is already in hand). Use for 'we decided', 'record this decision', 'document why we chose X', 'make it our standard', 'draft an RFC', 'should we switch to Y' proposals, 'resolve the RFC', 'we accepted the proposal', 'document the auth module', 'capture how the payment system works', reference material, how-to instructions, or a user flow with examples over an existing spec. Name the type inside the subject to skip the type question. Planning a feature or an intended user journey → /archcore:plan. Checking docs against code or docs health → /archcore:review." --- # /archcore:document Record the present state: a technical decision, existing code, or a supplied research material. The first word of the arguments selects the mode; a gate inside the mode's track selects the document type. Write affinity: knowledge types; a filed `research` and the decision cascade's `plan` belong to vision. The standard cascade can add a `cpat` (experience). Command tense: `/archcore:plan` declares a future canon delta, `/archcore:document` records the present state — including work that shipped without a plan — and `/archcore:review` reconciles a past declared delta. Δ vocabulary: `skills/_shared/delta-routing.md`. Load `skills/_shared/gate-contract.md` and `skills/_shared/elicitation-contract.md` before executing any gate. ## Modes | Mode | Track and entry | Types the entry gate selects | |---|---|---| | `decision` | `skills/_shared/tracks/decision.md`, `decision.classify` | `adr`, `rfc`; `rule` through the standard cascade; an existing `rfc` draft on the topic → `decision.resolve`, which records an `adr` on an accepted verdict | | `code` | `skills/_shared/tracks/describe.md`, `describe.read` | `spec`, `doc`, `guide`, `scenario` | | `research` | `skills/_shared/tracks/research.md`, `research.frame` | `research`, `rnd` by the closing test; one external material → `evidence` | A document type name is not a mode. When the subject text names a type (`skills/_shared/gate-contract.md`, Entry terms) that the mode's track produces, the selecting gate treats that type as settled and asks no type question: `document decision rfc for gRPC` reaches the RFC branch. A leading word that is not a mode is topic text and goes through classification (Step 3). No mode produces a `journey`; an intended user path belongs to `/archcore:plan`. ## When to use - "We decided to go with microservices" — settled decision - "Record the decision to use PostgreSQL" - "Document why we chose JWT over sessions" - "Make this our team standard for error handling" - "Draft an RFC for switching from REST to gRPC" - "Should we switch to Kubernetes?" — open proposal - "We accepted the proposal — resolve the RFC" — proposal resolution - "Document the auth module" - "Capture how the payment system works" - "Create reference docs for the config system" — reference material - "Write a guide for the release process" — how-to instructions - `document code scenario for checkout` — a user flow with examples over an existing spec - `document research <report>` — file a ready investigation - `document research <material>` — file one external material as evidence **Not document:** - Planning a feature, an initiative, or an intended user journey → `/archcore:plan` - Checking documents against code, reviewing branch changes, or docs health → `/archcore:review` - First-time setup → `/archcore:init` ## Routing table | Signal | Route | |---|---| | No arguments | → git investigation of the branch changes, then one classifying question (Step 3, Unclear) | | The first word is a mode — `decision`, `code`, `research` | → mode entry, no routing (Step 2) | | Decision signals: "we decided", "record this decision", "document why we chose X", "make it our standard", "draft an RFC", a "should we switch to Y" proposal. A bare "compare X vs Y" with no proposed target belongs to `/archcore:plan`'s research track; a proposal to add a new capability with no named technical target ("should we add caching?") is feature framing → `/archcore:plan`, sdd track | → decision track — `skills/_shared/tracks/decision.md`, entry at `decision.classify` | | Resolution signals: "resolve the RFC", "we accepted the proposal", "reject the RFC" — an `rfc` draft exists on the topic | → decision track — `skills/_shared/tracks/decision.md`, entry at `decision.resolve` | | Code-doc signals: "document the auth module", "capture how the payment system works", reference material (registry, glossary, lookup), how-to instructions, a user flow with examples over an existing `spec` | → describe track — `skills/_shared/tracks/describe.md`, entry at `describe.read` | | Research-material signals: a supplied investigation report, benchmark, transcript, or vendor document to file as is | → research track — `skills/_shared/tracks/research.md`, entry at `research.frame` | | Unclear | → git investigation, then one classifying question (Step 3) | ## Execution ### Step 1: Ground Apply `skills/_shared/research-compatibility.md` under its condition 1 — a request or type naming `research` or `evidence`, the research track, or a grounding result of either type. If this skill has no shell tool and no probe result was supplied, report `needs-vocabulary-probe` with the helper path and stop before the first MCP call that names either type. Before delegating research or evidence work, pass the current vocabulary probe result and absolute plugin root to the assistant. If the assistant returns `needs-vocabulary-probe`, run the helper and resume the same task. Before delegating any other document write or relation work, pass the absolute plugin root to the assistant. The assistant reads `skills/_shared/relation-authoring.md` under that root. Apply `skills/_shared/actor-subject-compatibility.md` under its own condition 1 — a request whose subject names `scenario` or `journey`, or a grounding result of either type. When that probe returns `yes`, add `scenario` and `journey` to the type filter below. On older engines, keep the legacy filter; a `code` request whose subject names `scenario` then reports the required version and exits without a write. When the probe returns `yes`, add `research` and `evidence` to the type filter below. On older engines, keep the legacy filter. Search `.archcore/` on the request topic across all three categories — vision, knowledge, experience. Do not exclude a category from reads. Pass a type filter matched to this command's moment (`adr`, `rfc`, `spec`, `doc`, `guide`, `rule`, plus `rnd` as decision evidence, and `research` and `evidence` when the probe returned `yes`) instead of relying on the global type ranking. When a found document carries `implements`, `depends_on`, or `related` relations, pull the linked documents one hop across categories. Duplicate handling lives in the tracks' check-existing gates — do not resolve duplicates here. If `.archcore/` does not exist, announce initialization in one line and call `mcp__archcore__init_project` without asking a question. If `.archcore/` exists but contains no documents, proceed on outer-context grounding and report that zero documents were found. **Global sources.** If a `mcp__archcore__list_documents` / `mcp__archcore__search_documents` result has `global: true` / `read_only: true` / `source_kind: "global"`, load `skills/_shared/globals.md`. Also load it when a `search_documents` response's `coverage` names a source other than `"local"` — even when `results` is empty: the empty page is exactly where that file's retry ladder applies. Never modify a global document and never target one with `add_relation`. Absent any global match, proceed as usual.README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/archcore-ai-archcore-plugins-archcore-skills-document.md