Documentation

Everything you need to set up and use Archie effectively.

Overview

Archie is a set of files you drop into your project root. It gives your AI coding agent three things it doesn't have on its own: persistent memory that survives across sessions, role-based skills that separate design from implementation, and approval gates that keep you in control.

The core idea is that AI agents are powerful but unstructured. Without guardrails, they make architecture decisions you never approved, refactor code outside the task scope, and produce massive PRs that are impossible to review. Archie prevents this by giving the agent a workflow: design first, get approval, then implement in small, reviewable chunks.

Compatibility: Works with Claude Code today. The framework is agent-agnostic (markdown files and conventions), with support for Cursor, Windsurf, and others coming soon.

Setup

Option A — Automated (recommended)

Copy Archie into your project, open Claude Code, and run:

/setup

The setup skill walks you through project bootstrapping interactively. It asks for your project name, services, tech stack, and VCS settings, then populates archie.config.json and all memory files in one pass.

Option B — Manual

1. Copy the files

cp -r archie/. your-project/

2. Edit archie.config.json

Replace every [PLACEHOLDER] with your project details — project name, service names, directories, VCS platform.

3. Rename per-service files

For each service, rename template files (replace [service] with your actual service name, e.g. api):

mv "memory/[service]" memory/api
mv "memory/agent-state/dev-agent-[service].md" memory/agent-state/dev-agent-api.md
mv "memory/tasks/dev-agent-[service].md" memory/tasks/dev-agent-api.md

4. Fill in memory files

Open files in memory/project-context/ and replace prompts with your project information. Priority: MEMORY.md → architecture.md → tech-stack.md → code-patterns.md.

5. Verify

Run /status to confirm everything is connected.

Memory System

All persistent context lives in the memory/ directory. The agent reads these files at the start of every session. This is how it knows your architecture, patterns, decisions, and current work.

memory/MEMORY.md

Project index — the first file read every session. Links to everything else.

memory/project-context/architecture.md

System design, component overview, how services communicate.

memory/project-context/tech-stack.md

Languages, frameworks, databases, key libraries and versions.

memory/project-context/development-setup.md

How to run, test, and build locally.

memory/patterns/code-patterns.md

Naming conventions, patterns, anti-patterns, testing rules.

memory/decisions/ADRs.md

Architecture Decision Records — why things are the way they are.

memory/features/epic-backlog.md

Feature pipeline — ideas, active epics, completed work.

memory/backlog/tasks.md

Dev agent task queue — what gets implemented next.

memory/debugging-insights/known-issues.md

Known bugs, workarounds, and gotchas.

memory/[service]/MEMORY.md

Per-service context — entry points, key files, dependencies.

memory/agent-state/dev-agent-[service].md

Agent progress tracking — current task, blockers, session log.

Size limit: Each memory file must stay under 300 lines. When a file approaches the limit, split it into sub-files and update the index in MEMORY.md.

Skills Reference

/setup— Bootstrap a new project

When to use: First time using Archie on a project. Populates config and all memory files interactively.

Output: archie.config.json + all memory files filled in with real project data.

/status— Quick project overview

When to use: Any time — to see active epics, task queue, agent state, and suggested next action.

Output: Read-only summary. Doesn't modify any files.

/standup— Generate a standup report

When to use: Start of day, before a sync, or any time you need a quick summary of what's done, in-progress, blocked, and up next.

Output: Formatted standup report with task statuses, PR/MR links, blockers, and risk flags. Read-only — doesn't modify any files.

/architect— Design a feature

When to use: You have a feature idea (especially L/XL complexity) and want to design it before coding.

Output: Epic entry in memory/features/epic-backlog.md with component impact, data model, API changes, and risk analysis.

/tech-lead— Break an epic into tasks

When to use: An approved epic exists and you want implementable task breakdown.

Output: Story + task breakdown with done-when criteria. Tasks auto-injected into memory/backlog/tasks.md on approval.

/quick— Fast-track for S/M features

When to use: You have a small or medium feature that doesn't need a full architecture review.

Output: Epic + task breakdown + backlog injection — all in one pass with one approval gate.

/dev-agent— Implement one task (in an isolated worktree)

When to use: Tasks are in the backlog and you're ready to implement. Run multiple agents in parallel — each gets its own git worktree.

Output: Isolated worktree, implementation, tests, commit, and a PR/MR. Task lock released, backlog and agent state updated.

Pro

Quality & Review Skills

/security-review— Audit code for security vulnerabilities

When to use: Before a release, after major changes, or as part of a regular security cadence. Reviews against OWASP categories, dependency CVEs, secrets detection, auth/authz, API security, and business logic flaws.

Output: Structured findings report by severity (Critical → Low). Optionally injects findings into backlog as prioritized tasks.

/code-review— Review code for quality and correctness

When to use: After a PR, after a sprint, or when you want a second opinion on code quality. Reviews correctness, architecture compliance, performance, readability, error handling, testing, and type safety.

Output: Structured review categorized as Must Fix / Should Fix / Consider. Optionally injects items into backlog as prioritized tasks.

/test-plan— Generate comprehensive test plans

When to use: Before implementing tests for a task, epic, or module. Analyzes the change surface, maps integration points, and identifies edge cases your tests should cover.

Output: Prioritized test matrix (P0/P1/P2) with specific inputs and expected outputs for unit tests, integration tests, edge cases, and regression risks. Optionally injects [test]-prefixed tasks into the backlog.

/retro— Sprint retrospective

When to use: At the end of a sprint or milestone. Analyzes git history, task archive, and agent state to surface what went well, what didn't, and why.

Output: Evidence-based retrospective with velocity metrics, quality analysis, and concrete action items. Optionally injects [retro]-prefixed improvement tasks into the backlog.

Workflows

Full Workflow (L/XL features)

/architect  →  approve  →  /tech-lead  →  approve  →  /dev-agent
  design         ✓          break down      ✓          implement

Fast-Track (S/M features)

/quick  →  approve  →  /dev-agent
  design + tasks   ✓     implement

When to use which

Full workflow — multiple services affected, schema migrations, new infrastructure, significant risk, or when you need a thorough design review.

Fast-track — touches 1–2 services, no major architectural decisions, no new infrastructure. If /quick detects the feature is actually complex, it redirects you to /architect.

Skip to backlog — for bug fixes and small improvements, add tasks directly to memory/backlog/tasks.md and run /dev-agent.

Approval gates accept natural language. You can say "looks good", "yes", "lgtm", "go ahead", "ship it" — any affirmative response works.

Backlog Management

Tasks are automatically injected by /tech-lead or /quick when approved. You can also add tasks manually for bug fixes and ad-hoc work.

Each task has: an ID (T-XXX), a service assignment, done-when criteria, a file list, and test requirements. Tasks are processed in order — the dev agent always picks up the top pending task assigned to its service.

Completed tasks should be moved from memory/backlog/tasks.md to memory/backlog/tasks-archive/index.md. Keep the active backlog short — under 10 tasks.

If a dev agent discovers something out of scope during implementation, it logs a new task to the backlog instead of implementing it. This keeps PRs focused and reviewable.

Parallel Dev Agents

Multiple dev agents can run simultaneously. Each agent works in its own git worktree — an isolated copy of the repo that prevents agents from interfering with each other.

How it works

1. Claim — The agent locks a task by setting Locked By in the backlog. If a task is already locked, it skips to the next one.

2. Isolate — The agent creates a worktree at .worktrees/T-XXX/ branched from the target branch. All work happens there.

3. Build — Normal implementation flow: code, test, commit (Conventional Commits), open PR/MR.

4. Release — On completion, the lock is released and the task moves to done. The worktree stays until the PR is merged.

5. Clean up — After merge: git worktree remove .worktrees/T-XXX

Configuration

Set in archie.config.json under devAgent:

Setting	Default	Purpose
`isolation`	`worktree`	Isolation strategy — each agent gets its own working copy
`maxParallel`	`3`	Maximum concurrent dev agents
`worktreeDir`	`.worktrees`	Directory for worktrees (add to .gitignore)
`commitConvention`	`conventional`	Commit message format standard
`lockTimeout`	`30m`	Stale lock threshold before asking the human

Safety rule: If two tasks touch overlapping files, don't run them in parallel. Sequence them instead, or have the Tech Lead split the work differently.

Multi-Service Projects

Each service gets its own skill, memory file, and agent state:

.claude/skills/dev-agent-api/SKILL.md

.claude/skills/dev-agent-web/SKILL.md

memory/api/MEMORY.md

memory/web/MEMORY.md

memory/agent-state/dev-agent-api.md

memory/agent-state/dev-agent-web.md

Tasks in the backlog are assigned to a specific agent. Dev agents only pick up tasks for their service. You can run them independently — they don't block each other unless their tasks share dependencies.

VCS Integration

Set vcs.platform and vcs.cli in archie.config.json:

Platform	CLI	Term	Create
GitHub	`gh`	pull request	`gh pr create`
GitLab	`glab`	merge request	`glab mr create`
Bitbucket	`bb`	pull request	`bb pr create`
None	`—`	—	`git push (manual)`

Commit Convention

All dev agent commits follow the Conventional Commits standard. This makes git history readable, enables automated changelogs, and works with semantic versioning tools.

<type>(<scope>): <description>

# Examples:
feat(T-001): add user authentication endpoint
fix(T-012): handle null pointer in dashboard filter
refactor(T-045): extract payment logic into service layer
test(T-003): add integration tests for order flow

Type	When to use
`feat`	New feature or capability
`fix`	Bug fix
`refactor`	Code change with no new feature or bug fix
`test`	Adding or updating tests
`docs`	Documentation only
`chore`	Build, tooling, dependency updates
`perf`	Performance improvement
`ci`	CI/CD pipeline changes

Rules & Limits

1.Always read memory/MEMORY.md at the start of every session

2.Never implement something not in the current task scope — log discoveries to the backlog

3.Never commit secrets, credentials, or API keys

4.Each task targets one service and touches ≤ 15 files

5.Memory files must stay under 300 lines — split if approaching the limit

6.Use memory/scratchpads/chat/ for temporary working notes (gitignored)

7.Read memory/patterns/code-patterns.md before writing any code

8.Always work inside a git worktree — never modify the main working tree during implementation

9.Always claim (lock) a task before starting — never work on a task locked by another agent

10.Follow Conventional Commits format for all commit messages

CLAUDE.md Templates

Archie works alongside a CLAUDE.md file — the per-project instruction file your AI agent reads at the start of every session. While Archie handles workflow (what to build and when), the CLAUDE.md handles conventions (how to write code for this specific stack).

We provide free enterprise-grade CLAUDE.md templates for popular stacks. Each one covers project structure, naming conventions, component/module patterns, data fetching, error handling, validation, state management, testing, security, and git workflow.

Next.js

App Router, Server Components, Server Actions, Tailwind

React (Vite)

Zustand, TanStack Query, React Hook Form, Zod

Node.js (Express)

Three-layer architecture, Prisma, Zod, pino

cmd/internal layout, sqlc, slog, interface-based DI

Angular

Standalone components, Signals, NgRx SignalStore, @defer

Download all 5 templates for free — enterprise coding standards that work with Claude Code, Cursor, and any AI agent that reads markdown.

Tips

Be specific in the Architect phase. Vague problem statements produce vague designs. The more precise your answers, the better the output.

Keep tasks small. A task that takes more than one focused session is too large. Ask the Tech Lead to split it.

Don't skip the read step. Every skill starts by reading memory files. Skipping this means the agent works without context and makes mistakes.

Use the scratchpad. During complex sessions, ask Claude to keep notes in memory/scratchpads/chat/[date].md. Helps resume interrupted work.

Trust the gate. The sign-off gates exist because AI agents are good at moving fast in the wrong direction. A 2-minute review saves hours of rework.

Use /status often. It's fast, free, and keeps you oriented — especially after a break.

Want to see Archie in action? Check out the full walkthrough.