ArPiDoc — AGENTS.md (V2.1 Core-First Bootstrap)#

This file is the single mandatory entry point for AI agents using ArPiDoc.

Mission:

1. detect the repo workflow state,
2. select exactly one role (Architect / Pilot / Documenter),
3. execute the next concrete action immediately.

This file is English-only. Do not rewrite or translate it.

0) Language policy#

• This file stays in English.
• Chat replies must match the user's language.

1) What ArPiDoc is (and is not)#

ArPiDoc is a lightweight orchestration method for documentation work on evolving projects.

It exists to provide:

• clear documentation steps and handoffs,
• visible traces of what was documented and why,
• clean pause/resume points,
• logical documentation commits when requested.

It does not replace the agent's native skills (source reading, repo exploration, git usage, diagnostics, IDE history, diff reading).

2) User control guarantees (core promises)#

These are the non-negotiable outcomes of the method:

• User override wins: the user can redirect scope, target docs, or priorities at any time.
• No hostage flow: after a story is closed, the user may pause immediately.
• Visible reasoning: story logs must explain what was documented and why.
• Assisted work, not blind generation: work happens against a story with testable Done when.
• Long-project continuity: TASKS.md + one active story keep documentation work legible.
• Open-source friendly commits: commit proposals can be required by SPEC.md.

3) Native agent behavior is preserved#

ArPiDoc does not replace the agent's default capabilities.

• Keep using platform-provided context and signals (IDE/chat history, diagnostics, file diffs, git status, recent commits, tool outputs).
• The ArPi scan below is only for workflow routing.
• Use the smallest additional reads/commands needed to act safely.

4) Core vs optional artefacts#

Core (default)#

• ArPiDoc/SPEC.md
• ArPiDoc/TASKS.md
• ArPiDoc/stories/*.md

Optional (use only when helpful)#

• ArPiDoc/DECISIONS.md (cross-story or repeated documentation decisions)
• custom models under ArPiDoc/models/ (only if standard models are not a good fit)

5) Cross-method context (ArPiDev)#

If ArPiDev/ exists:

• treat ArPiDev artefacts as source context (read-only)
• prefer high-signal inputs: done stories, To document: notes, user-visible/API/config/ops changes
• do not edit ArPiDev artefacts while operating under ArPiDoc

6) V1/V2/V2.1 compatibility#

• Read older ArPiDoc TASKS.md and story files leniently.
• Missing newer sections is not an error by default.
• Treat format drift as an inconsistency only when it blocks safe execution or closure.
• Prefer minimal Pilot backfill over full rewrites.

7) Read-only index (load only what you need)#

ArPiDoc/
  AGENTS.md
  stories/
  models/
  definitions/
    agents/
      architect.md
      pilot.md
      documenter.md
    artifacts/
      spec.md
      tasks.md
      story.md
      decisions.md
      documentation.md
      doc_model.md
      naming.md
    models/
      ... standard models ...

Authoritative sources:

• role behavior/permissions: ArPiDoc/definitions/agents/*.md
• artifact formats: ArPiDoc/definitions/artifacts/*.md
• standard models: ArPiDoc/definitions/models/*.md

Do not bulk-read the whole method when a smaller read is enough.

8) Required response header (operational replies)#

Use this header in every operational response:

• Line 1: Role: <Architect|Pilot|Documenter>
• Line 2: Next: <one sentence describing the next action>

9) Bootstrap algorithm (same response)#

If the user asks to use ArPiDoc / read this file:

1. Acknowledge reading ArPiDoc/AGENTS.md.
2. Detect the workflow state (§10).
3. Classify intent (framing / planning / execution / closure / method update).
4. Select one role (§11).
5. Read the selected role file.
6. Read only the artefacts/models needed for the immediate action.
7. Execute one concrete step now (not a transition-only reply).

10) Workflow state detection (lean)#

Scan these paths for routing:

• ArPiDoc/SPEC.md
• ArPiDoc/TASKS.md
• ArPiDoc/stories/

Optional if present (read only when useful for the current step):

• ArPiDoc/DECISIONS.md

Treat “empty” as missing / whitespace-only / placeholder-only.

Active story inference (lenient)#

Preferred order:

1. TASKS.md line: Active story: <id> or Active story: NONE (...)
2. one explicit active marker in TASKS.md (ACTIVE, NOW, IN PROGRESS)
3. first unchecked story not marked [PENDING] in the earliest unfinished task

If multiple candidates remain, state is inconsistent.

States#

• Empty: no usable SPEC.md, no usable TASKS.md, no story files
• Framing: SPEC.md exists, TASKS.md missing/empty
• Planning: TASKS.md exists, but no executable story file yet
• Execution: one clear active story exists
• Waiting: no active executable story (validation/pending/user pause)
• Inconsistent: ambiguous active story, broken references, contradictory statuses, or blocking format drift

This routing scan must not prevent normal agent behavior (git history, recent edits, diagnostics, etc.).

11) Role selection (practical)#

Choose exactly one role:

• Architect: framing the documentation work and writing SPEC.md (and optional custom model)
• Pilot: planning, story creation, closure, pause/resume, migration backfill
• Documenter: executing the active documentation story and documenting the work in that story

Routing hints:

• Empty -> Architect
• Framing, Planning, Waiting, Inconsistent -> Pilot (unless user explicitly asks to reframe docs/model -> Architect)
• Execution -> Documenter (unless user asks orchestration/policy/method changes -> Pilot)
• method update request -> Pilot for coordination, or direct method edit if explicitly requested

12) If unsure#

1. Re-read this file.
2. Re-read the selected role file.
3. Re-read only the relevant artifact guide(s) / model file.
4. Ask the user only if uncertainty remains.