# FlyDocs Agent Instructions Shared instructions for every coding agent working in this repository — Claude Code, Cursor, Codex, Windsurf, and others. This file is the single source of shared agent instructions: `.claude/CLAUDE.md` imports it and adds only Claude Code-specific sections; Cursor reads it natively alongside `.cursor/rules/`. Shared instructions live here, once. This file stays small on purpose: rules that must always be in context live here; reference detail lives in `.claude/skills/flydocs-workflow/` and is read on demand. ## Hard Rules These are non-negotiable (Claude Code additionally enforces them with hooks): 1. **Tools first for issue operations.** Call the `flydocs` MCP tools for the hot path (`issue_get`, `issue_create`, `issue_activate`, `issue_transition`, `issue_comment`, `issue_acceptance_update`, `session_start`, `session_wrap`, `project_update`); everything else runs through `flydocs run `, with the dispatcher scripts as a working fallback. Never describe an action you should execute. 2. **Every status transition gets a comment.** No silent moves. Use the comment templates from the workflow skill. 3. **Assignment required before In Progress.** Hard gate — `issue_activate` assigns and transitions in one call; the relay refuses the transition otherwise. 4. **Checkboxes live in issue description** — change them with `issue_acceptance_update` (fallback `issues.py acceptance`), never via raw description writes or comments. 5. **Session wrap posts a project update.** `session_wrap` posts the end-of-session update itself; `project_update` is for mid-session ones. 6. **No secrets in commits.** Never commit `.env`, credentials, or API keys. ## Automatic Workflow Behavior These behaviors are **always on**. Execute them automatically as part of doing the work — do not wait for explicit commands. Where a `flydocs` MCP server is configured, these are tool calls. Where it is not, the script in brackets does the same job and still works. - **Starting work** → one call assigns and transitions: `issue_activate` with `ref`, `assignee`, `comment` [`issues.py assign REF ASSIGNEE` then `issues.py transition REF IMPLEMENTING "Starting implementation"`] - **Completing implementation** → transition with summary: `issue_transition` → REVIEW, `comment: "Implementation complete — [summary]"` [`issues.py transition REF REVIEW "…"`] - **Closing** → verify AC, then transition: `issue_transition` → COMPLETE, `comment: "All acceptance criteria verified"` [`issues.py transition REF COMPLETE "…"`] - **Every transition gets a comment** — no silent moves, no exceptions - **Checkboxes in description, never comments** — update AC as you go, by criterion id, never by rewriting the description: `issue_acceptance_update` with `changes: [{ criterionId: 1, status: checked }]` (`status: deferred` + `deferredTo` when the remainder moved to another issue) [`issues.py acceptance REF --check 1,3` / `--defer N:FLY-1234`] - **Session wrap posts a summary** — `session_wrap` posts the project update itself [`session.py wrap --health onTrack --body-file FILE`] Tool arguments are structured: multi-line markdown bodies go straight into the `comment`, `body` or `description` parameter — no temp files, no shell quoting. ## Efficiency For workflow operations (issue creation, status transitions, session management), the stage files in `.claude/skills/flydocs-workflow/` carry the required procedures — read the relevant one before acting. For general coding, research, and building features, do NOT read skill files or workflow documentation first: the rules above are already in your context — just do the work. ## Workflow The development lifecycle follows seven stages: ``` Capture → Refine → Activate → Implement → Review → Validate → Close ``` Each stage has a required procedure in `.claude/skills/flydocs-workflow/stages/` — the Stage Index and Reference tables in `.claude/skills/flydocs-workflow/SKILL.md` map every workflow action (stages, sessions, knowledge capture, PR conventions, comment templates, status transitions, priorities, issue templates) to its file. Read the stage file before performing a manual workflow action. ## Surfaces Hot-path lifecycle operations are MCP tools on the `flydocs` server — the invocation matrix in `.claude/skills/flydocs-workflow/SKILL.md` maps each need to its tool and its fallback. Long-tail operations (audits, milestones, labels, workspace and graph) run through `flydocs run `, described below. ## Operations Everything outside the hot path is an operation ID on `flydocs run`. The ID is `domain.verb` (`issue.audit`, `milestone.create`, `workspace.validate`, `graph.query`, …) and never names a file, so one permission rule (`Bash(flydocs run:*)`) covers the whole surface: ```bash flydocs run issue.audit --limit 20 flydocs run --list # every operation ID ``` The full catalog — every domain, operation, and argument — is `.claude/skills/flydocs-workflow/reference/script-catalog.md`. The dispatcher scripts in `.claude/skills/flydocs-workflow/scripts/` implement all of them and remain the fallback where neither MCP nor the `flydocs` binary is available. **Long bodies go in a file.** A description or update body belongs in `.flydocs/scratch/.md`, passed as `--file` — never inline in a `flydocs run` argument. ## Multi-Repo Workspaces In a multi-repo workspace, skills and scripts live at the workspace root (`.claude/skills/` — any `.claude/` content inside child repos is legacy; ignore it), while config and context live in each child repo (`.flydocs/config.json`, `flydocs/context/`). `flydocs run` needs no `cd`: it finds the owning repo from the working directory, or takes `--repo ` from the workspace root. Full topology rules and examples: `.claude/skills/flydocs-workflow/reference/multi-repo.md`. ## Project Context | File | Purpose | | ------------------------------ | ------------------------------------------------- | | `flydocs/context/project.md` | Product scope, tech stack, active priorities | | `flydocs/context/service.json` | Service descriptor, topology, cross-repo context | | `.flydocs/config.json` | Tier, provider, labels, active projects, topology | ## Further Reference Read on demand — not needed until the situation arises: - **Protecting local edits from `flydocs update`** (`artifactOverrides.skipPaths`) and **API key setup/resolution** (`flydocs init` / `flydocs auth`): `.claude/skills/flydocs-workflow/reference/cli-config.md` - **Writing or editing copy** (product docs, marketing pages, website, wikis): read `.claude/skills/flydocs-workflow/reference/writing-style.md` first; the `human-writing` skill goes deeper. ## Output Formatting Apply in every response — summaries, issue comments, status updates, plans: - Lead with a one-line summary or status; keep paragraphs to 2-3 sentences. - Status labels bolded: **Completed**, **In Progress**, **Blocked**, **Next Up**. - Issue refs as `FLY-123`; file paths, commands, and identifiers in backticks; dates as `YYYY-MM-DD`. - No emoji unless the user explicitly requests it. Full conventions (structure, tables, readability): `.claude/skills/flydocs-workflow/reference/output-formatting.md`. ## Skills Index Consult the workflow skill for **issue operations and status transitions only**. For general coding tasks, skip this — just write code. | Skill | Triggers | Entry | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | flydocs-workflow | create issue, capture issue, log a bug, add to backlog, transition, move to, mark as, set status, assign issue, close issue, start session, wrap session, project update, status update, add comment, set priority, set estimate | .claude/skills/flydocs-workflow/SKILL.md | ## Platform Configuration | Platform | Primary Config | | ------------------------- | ----------------------- | | Claude Code | `.claude/CLAUDE.md` | | Cursor | `.cursor/rules/*.mdc` | | Codex / Windsurf / Others | This file (`AGENTS.md`) |