Agent instructions, reusable skills, and a deterministic workflow controller that expose the agent's decisions, so you can understand and steer the development instead of reviewing a finished diff you never saw coming.
Unseen decisions are the risk in AI development. This repository lets you choose, per task, where your attention goes: the result, the design and its documentation, or every step. Whatever you choose, the agent records requests, questions, and design choices, and it stops at gates where only your explicit approval moves the work forward. Those decisions and approvals need to survive beyond a chat session, so this repository supplies shared engineering policy and skills, with an executable controller, every flow's saved state in tmp-agent-wip.json, and a live progress page, tmp-agent-progress.html, at the host root.
Install Git and Python 3 first. The PowerShell setup skill remains for repositories whose tools still need pwsh.
git clone https://github.com/an-dr/agents.git
cd agents
python skills/_repository/an-dr-agents-repo-install/scripts/install-agents.py
python skills/_repository/an-dr-agents-repo-install/scripts/verify-agents.pyThe installer adds a managed policy reference and links the skills into supported tools' user configuration. It handles Claude Code, Codex, GitHub Copilot CLI, DeepSeek Harness, Gemini CLI, and opencode; its current skill-link support covers the first four, while Gemini CLI and opencode receive policy references. See the installation skill for tool selection, updates, conflicts, and removal.
Open the project you want to change in your AI tool and select a flow in the request:
Vibe: fix the parser's handling of empty input. Preserve its public API.
| Flow | Your attention goes to | You decide | Where it lands |
|---|---|---|---|
| Vibe | The result | land, redo, or drop after trying it | vibe/<slug> branch, fast-forwarded into the base on land |
| Spec-driven | The design, then the docs | implement after the design talk, accept after the review | spec/<slug> branch and pull request, or the base on request |
| Supervised | Every step | intake, implement, each increment's verification, accept | supervised/<slug> branch and pull request |
Work branches are pushed to the remote automatically; the base branch never is. For gated work, the workflow controller skill owns the commands and transitions. The agent resumes existing state instead of reconstructing it from conversation history. AGENTS.md defines the policy, including the separate review rule for changes to this process repository.
The three flows sit on one line: how much of your attention a change takes, and how much the agent does alone in exchange. You always name the flow yourself; the agent never infers it from task size.
quadrantChart
title Your attention versus agent autonomy
x-axis Little user attention --> Much user attention
y-axis Low agent autonomy --> High agent autonomy
quadrant-1 Supervised autonomy
quadrant-2 Hands-off
quadrant-3 Rare
quadrant-4 Pair work
Vibe: [0.15, 0.88]
Spec-driven: [0.5, 0.7]
Supervised: [0.85, 0.3]
Two questions pick it. Do you want to agree the design before any code? If not, Vibe shows you the result. If you do, do you want to check every increment, or review the docs and the pull request at the end?
flowchart TD
S([Task that changes files]) --> A{Agree the design first?}
A -- no --> V[Vibe]
A -- yes --> C{Check every increment?}
C -- no --> SD[Spec-driven]
C -- yes --> SU[Supervised]
Vibe β you judge the behaviour, not the code. The agent builds, tests, and reviews on a vibe/<slug> branch, then hands over one command, artefact, or screenshot that shows the change, what was tested, and its limits. You answer with one word.
flowchart TD
S([Vibe request]) --> B[Build and verify]
B --> H[Hand over result]
H --> C{Your choice}
C -- land --> L[Integrate and delete branch]
C -- redo --> B
C -- drop --> D[Delete branch]
L --> E([Done])
D --> E
Spec-driven β you shape the design; the agent does the rest. The documentation is the review surface: you check that the docs say what you agreed and that the behaviour matches the docs, with the change report and the pull request beside them.
You and the agent settle the design together. After implement, the agent builds every increment alone, and its draft pull request turns ready when the last one is done. You review it; comments send the agent back to work, and accept starts the handover.
stateDiagram-v2
direction LR
[*] --> DESIGN
DESIGN --> INCREMENTS: implement
INCREMENTS --> REVIEW
REVIEW --> INCREMENTS: comments
REVIEW --> HANDOVER: accept
HANDOVER --> [*]
classDef blackbox stroke-width:3px,stroke-dasharray:5 3
class INCREMENTS blackbox
A dashed, heavier box opens into a diagram of its own. Inside INCREMENTS, each increment goes the same way: documentation first, then code, verification by the agent, and a commit pushed to the pull request.
stateDiagram-v2
direction LR
[*] --> DOCS
DOCS --> BUILD
BUILD --> VERIFY
VERIFY --> COMMIT
COMMIT --> DOCS: next
COMMIT --> [*]: last
Supervised β every increment waits for your verification before the next begins. Use it for architecture-heavy or risky work, where catching a wrong turn early is worth your time.
Planning ends when you say implement. Each increment then waits for you, and the summary of the finished branch waits for your accept.
stateDiagram-v2
direction LR
[*] --> PLANNING
PLANNING --> INCREMENTS: implement
INCREMENTS --> SUMMARY
SUMMARY --> HANDOVER: accept
HANDOVER --> [*]
classDef blackbox stroke-width:3px,stroke-dasharray:5 3
class PLANNING,INCREMENTS blackbox
PLANNING is three steps: you close the request list with intake, then the design and the split into increments follow.
stateDiagram-v2
direction LR
[*] --> INTAKE
INTAKE --> DESIGN: intake
DESIGN --> SPLIT
SPLIT --> [*]
In INCREMENTS, nothing is committed until you verify it; a rejected increment goes back to BUILD.
stateDiagram-v2
direction LR
[*] --> DOCS
DOCS --> BUILD
BUILD --> VERIFY
VERIFY --> COMMIT: you verify
COMMIT --> DOCS: next
COMMIT --> [*]: last
Both flows end at HANDOVER: commits regrouped, the state marked handed over, the pull or merge request ready. Nothing is merged by the flow. When you ask, an-dr-dev-integrate lands the branch onto the base it started from β dev if the work began there β through its request with the repository's own merge method, or locally when there is no supported platform. Every file whose name starts with tmp- or .tmp-, the workflow state included, is stripped from the branch history on the way and never reaches the base.
- Shared engineering instructions available across projects through one global installation.
- Three flows by attention β Vibe, Spec-driven, Supervised β with explicit gates, resumable state, and a live progress page.
- Self-contained skills for specification, implementation, debugging, testing, review, documentation, and Git operations.
- HTML reports for code reviews, project overviews, and completed changes.
- Deterministic script checks and separate, explicitly requested agent evaluations.
- Flows that hand over a clean branch, and integration as a separate step you ask for: through pull or merge requests with the repository's merge method, or a local fallback that rebases before landing.
A global installation engages the workflow policy when the host project's root AGENTS.md or CLAUDE.md references this clone, an active tmp-agent-wip.json exists, or the user names a flow or one of its skills. Otherwise the skills remain available on request. Add a reference to the clone's AGENTS.md in the host's instruction file when the project should opt in permanently.
The installer's -Tools parameter limits which tools are configured. Re-run the installer after adding skills or moving the clone. Installation verification distinguishes broken links, missing project opt-in, and a running tool failing to load the policy.
Generated skill outputs live under .tmp-ai-gen/ according to the artifact layout convention. HTML diagram rendering requires a local Chromium-based browser; the HTML report convention describes rendering and visual verification.
Each release is a version in VERSION, with notes in docs/releases/, published on GitHub as agents-<version>.zip: the policy, this README, the license, and every skill except those under skills/_repository, which only maintain this repository. The release skill builds and publishes it.
- Engineering policy: workflow selection, approvals, delivery, and Git rules.
- Skill catalog: actions, concepts, conventions, and repository maintenance skills.
- Testing guide: local checks, evaluation requests, fixtures, and coverage limits.
- Skill testing convention: the evaluation contract and execution environment.
| Path | Purpose |
|---|---|
AGENTS.md |
Policy entry point |
VERSION |
The repository's version, released as agents-<version>.zip |
docs/releases/ |
Notes for each release |
skills/actions/ |
Procedures the agent performs |
skills/concepts/ |
Principles applied when their subject is in play |
skills/conventions/ |
Artifact formats and their mechanical checks |
skills/_repository/ |
Maintenance and installation of this repository |
tests/run-all.py |
Discovery of every skill test runner |
.tmp-ai-gen/ |
Ignored generated skill outputs, with a <kind>-latest copy of each |
Skills declare the other skills they name through metadata.an-dr.dependencies. The skill convention defines this contract and the portability rules: each skill owns its files, and callers pass the location of another skill's public script rather than assuming an installation layout.
The dependency builder derives the graph below from those declarations. Arrows point from a skill to its declared dependencies. Isolated skills are omitted; the graph describes instruction dependencies, rather than every runtime script call.
Show the generated dependency graph
flowchart LR
%% diagram-budget: exempt generated reference graph of every skill
subgraph g_repository["Repository"]
an-dr-agents-analyze-session
an-dr-agents-repo-build-dependencies
an-dr-agents-repo-build-release
an-dr-agents-repo-convention-skills
an-dr-agents-repo-install
an-dr-agents-repo-modify
an-dr-agents-repo-verify-installation
end
subgraph g_actions["Actions"]
an-dr-ai-collect-input
an-dr-ai-review-instruction
an-dr-ai-skill-implement-test
an-dr-ai-skill-test
an-dr-ai-use-user-interface
an-dr-ai-use-wip-data
an-dr-ai-write-instruction
an-dr-architecture-fix-dependencies
an-dr-dev-analyze-changes
an-dr-dev-analyze-slop
an-dr-dev-assign-ai-level
an-dr-dev-debug
an-dr-dev-design
an-dr-dev-follow-workflow
an-dr-dev-implement-adversarial-ut
an-dr-dev-implement-code
an-dr-dev-implement-pipeline
an-dr-dev-integrate
an-dr-dev-review
an-dr-dev-test
an-dr-dev-write-documentation
an-dr-dev-write-readme
an-dr-dev-write-specification
an-dr-env-install-powershell
an-dr-files-build-report
an-dr-files-make-screengif
an-dr-files-make-screenshot
an-dr-git-modify-history
an-dr-project-write-overview
an-dr-text-analyze-slop
an-dr-text-verify-claims
an-dr-text-write-curated
end
subgraph g_concepts["Concepts"]
an-dr-concept-ai-slop
an-dr-concept-clean-dependencies
an-dr-concept-dark-cockpit
an-dr-concept-evidence-grounding
an-dr-concept-single-authority
end
subgraph g_conventions["Conventions"]
an-dr-convention-adr
an-dr-convention-agent-skill
an-dr-convention-agent-skill-testing
an-dr-convention-ai-level
an-dr-convention-artifact-layout
an-dr-convention-code
an-dr-convention-commit-message
an-dr-convention-diagram
an-dr-convention-html-repo-style
an-dr-convention-html-report
an-dr-convention-layout
an-dr-convention-markdown
an-dr-convention-readme
an-dr-convention-script
an-dr-convention-use-case
end
an-dr-agents-analyze-session --> an-dr-agents-repo-modify
an-dr-agents-repo-build-dependencies --> an-dr-ai-use-user-interface & an-dr-convention-agent-skill
an-dr-agents-repo-build-release --> an-dr-ai-use-user-interface & an-dr-git-modify-history
an-dr-agents-repo-convention-skills --> an-dr-ai-skill-implement-test & an-dr-ai-skill-test & an-dr-convention-agent-skill & an-dr-dev-test & an-dr-dev-write-documentation & an-dr-convention-agent-skill-testing
an-dr-agents-repo-install --> an-dr-ai-skill-test
an-dr-agents-repo-modify --> an-dr-agents-repo-convention-skills & an-dr-agents-repo-install & an-dr-agents-repo-verify-installation & an-dr-ai-review-instruction & an-dr-ai-use-user-interface & an-dr-ai-skill-implement-test & an-dr-ai-skill-test & an-dr-ai-write-instruction & an-dr-convention-agent-skill & an-dr-convention-markdown & an-dr-convention-script & an-dr-git-modify-history
an-dr-agents-repo-verify-installation --> an-dr-agents-repo-install & an-dr-ai-skill-implement-test & an-dr-ai-skill-test & an-dr-ai-use-wip-data & an-dr-convention-commit-message
an-dr-ai-collect-input --> an-dr-ai-use-user-interface & an-dr-concept-ai-slop & an-dr-concept-evidence-grounding
an-dr-ai-review-instruction --> an-dr-ai-use-user-interface
an-dr-ai-skill-implement-test --> an-dr-ai-write-instruction & an-dr-convention-agent-skill & an-dr-convention-script & an-dr-convention-agent-skill-testing
an-dr-ai-skill-test --> an-dr-ai-skill-implement-test & an-dr-ai-use-user-interface & an-dr-files-build-report & an-dr-convention-script & an-dr-convention-agent-skill-testing
an-dr-ai-use-user-interface --> an-dr-concept-dark-cockpit & an-dr-convention-html-repo-style & an-dr-files-build-report
an-dr-ai-write-instruction --> an-dr-ai-review-instruction & an-dr-concept-ai-slop & an-dr-convention-markdown & an-dr-dev-write-documentation
an-dr-architecture-fix-dependencies --> an-dr-ai-use-user-interface & an-dr-concept-clean-dependencies & an-dr-files-build-report & an-dr-convention-html-report
an-dr-dev-analyze-changes --> an-dr-ai-use-user-interface & an-dr-concept-ai-slop & an-dr-convention-adr & an-dr-convention-diagram & an-dr-files-build-report & an-dr-convention-html-report & an-dr-dev-review & an-dr-dev-write-documentation
an-dr-dev-analyze-slop --> an-dr-ai-review-instruction & an-dr-ai-use-user-interface & an-dr-concept-ai-slop & an-dr-files-build-report & an-dr-convention-html-report
an-dr-dev-assign-ai-level --> an-dr-ai-use-user-interface & an-dr-convention-ai-level
an-dr-dev-design --> an-dr-ai-use-user-interface & an-dr-convention-adr & an-dr-convention-use-case & an-dr-dev-write-documentation
an-dr-dev-follow-workflow --> an-dr-ai-use-user-interface & an-dr-ai-use-wip-data & an-dr-convention-adr & an-dr-dev-analyze-changes & an-dr-dev-debug & an-dr-dev-design & an-dr-dev-implement-code & an-dr-dev-implement-pipeline & an-dr-dev-integrate & an-dr-dev-review & an-dr-dev-test & an-dr-dev-write-documentation & an-dr-dev-write-readme & an-dr-dev-write-specification & an-dr-git-modify-history
an-dr-dev-implement-code --> an-dr-convention-adr & an-dr-convention-code & an-dr-convention-layout & an-dr-dev-write-documentation
an-dr-dev-implement-pipeline --> an-dr-ai-use-user-interface & an-dr-convention-code
an-dr-dev-integrate --> an-dr-ai-use-user-interface & an-dr-ai-use-wip-data & an-dr-convention-commit-message & an-dr-git-modify-history
an-dr-dev-review --> an-dr-ai-use-user-interface & an-dr-concept-ai-slop & an-dr-concept-clean-dependencies & an-dr-concept-evidence-grounding & an-dr-convention-artifact-layout & an-dr-convention-code & an-dr-convention-html-repo-style & an-dr-convention-html-report & an-dr-convention-layout
an-dr-dev-test --> an-dr-ai-use-user-interface & an-dr-dev-implement-adversarial-ut
an-dr-dev-write-documentation --> an-dr-ai-use-user-interface & an-dr-concept-ai-slop & an-dr-convention-adr & an-dr-convention-diagram & an-dr-convention-markdown & an-dr-convention-use-case
an-dr-dev-write-readme --> an-dr-ai-use-user-interface & an-dr-dev-assign-ai-level & an-dr-convention-markdown & an-dr-convention-readme & an-dr-dev-write-documentation & an-dr-files-make-screengif & an-dr-files-make-screenshot
an-dr-dev-write-specification --> an-dr-ai-use-user-interface & an-dr-concept-clean-dependencies & an-dr-convention-adr & an-dr-convention-use-case & an-dr-dev-write-documentation
an-dr-env-install-powershell --> an-dr-ai-use-user-interface
an-dr-files-build-report --> an-dr-convention-artifact-layout & an-dr-convention-html-repo-style & an-dr-convention-html-report
an-dr-files-make-screengif --> an-dr-files-make-screenshot
an-dr-files-make-screenshot --> an-dr-files-build-report
an-dr-git-modify-history --> an-dr-convention-commit-message
an-dr-project-write-overview --> an-dr-concept-ai-slop & an-dr-files-build-report & an-dr-convention-html-report & an-dr-dev-write-documentation
an-dr-text-analyze-slop --> an-dr-ai-use-user-interface & an-dr-concept-ai-slop & an-dr-files-build-report & an-dr-convention-html-report
an-dr-text-verify-claims --> an-dr-ai-use-user-interface & an-dr-files-build-report & an-dr-convention-html-report
an-dr-text-write-curated --> an-dr-ai-use-user-interface & an-dr-text-verify-claims & an-dr-text-analyze-slop & an-dr-convention-artifact-layout
an-dr-convention-agent-skill --> an-dr-concept-clean-dependencies & an-dr-convention-script & an-dr-convention-agent-skill-testing & an-dr-convention-markdown
an-dr-convention-code --> an-dr-concept-ai-slop & an-dr-concept-clean-dependencies & an-dr-convention-layout
an-dr-convention-html-report --> an-dr-concept-dark-cockpit & an-dr-convention-artifact-layout & an-dr-convention-diagram & an-dr-convention-html-repo-style
an-dr-convention-layout --> an-dr-convention-artifact-layout
an-dr-convention-readme --> an-dr-concept-ai-slop & an-dr-concept-evidence-grounding & an-dr-convention-markdown
an-dr-convention-script --> an-dr-ai-use-user-interface & an-dr-convention-agent-skill-testing
Run the repository checks from the clone root:
python tests/run-all.pyThe runner discovers skill manifests and invokes each scripts/tests/run.py. By default it runs suites affected by uncommitted changes; python tests/run-all.py --all runs every suite, as CI does. Each suite owns its validators and regression tests; the testing convention's suite discovers evals/evals.json files and validates their ZIP fixtures. Missing runners and failed suites produce a nonzero exit code. Fixture scripts are excluded from test discovery.
Skills with scripts keep deterministic tests in scripts/tests/. Every skill has behavioral cases in evals/evals.json and evaluation intent in evals/EVAL.md; repository fixtures, when needed, are ZIP archives under evals/fixtures/. See the testing guide for commands and run limits. Syntax-only checks establish parsing coverage, and successful structural checks do not establish that an agent follows a skill.
GitHub Actions runs free checks on pushes and pull requests. CI installs the Agent Skills reference validator, skills-ref; local checks report its installation command when it is missing. Agent evaluations consume model usage and run only on explicit request, with declared environments and bounded attempts.
This repository values transparency about how software is made, and it encourages everyone to disclose AI usage in their repositories. Its own level is 3 (ASSISTED) on the ai-level.dev scale: AI wrote functional modules, and a human reviews every change before it enters history. The AI level convention defines the levels, and the assign skill assigns one to any repository, offered whenever a README is written.
Follow AGENTS.md for changes to this repository, use the skill convention when changing skills, and run the repository checks before proposing a change. Keep generated artifacts out of commits. This repository keeps no ADRs: state every decision in the skill or policy that owns it, so the skills and AGENTS.md are the record.
MIT, copyright 2026 Andrei Gramakov.
Actively maintained, with automated checks on pushes and pull requests. CI checks scripts and packaging; behavioral reliability requires separately executed agent evaluations.