⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

document

archcore-ai@archcore-ai⭐ 75 stars· last commit 8d ago· 14 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 75 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Archcore

Git-native project context for AI coding agents.The agent stops guessing and starts following the system.

License Release Platform Go Docs

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.

AgentSetup
Claude Code, Codex CLI, GitHub Copilot CLIThe installer adds the plugin
OpenCodearchcore init adds the plugin to the global OpenCode config, or run opencode plugin add @archcore/opencode-plugin. Details
Gemini CLI, Roo Code, Clinearchcore init connects them
CursorOne extra setup step

The documents stay in your repo, in .archcore/. Details: privacy.


Three commands

WhenCommandWhat 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:reviewThe 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 changeWhat plan prepares
A small fixNo documents
A settled choiceA decision record
A change to existing behaviorA check of the covering spec: update the spec, or fix the code
A sequenced migrationA plan
One new capabilityA spec and a plan
Several capabilitiesA 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

// REPO STATS

75 stars
14 open issues
Last commit: 8d ago