Skip to content
an-drPublic

About

AI workflow allowing to develop and understand, not just vibe-code

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

178 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ€– agents

Checks License: MIT AI Level 3 Agent Skills

Transparent AI development: you choose how much of your attention each change gets.

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.


Supported platforms:

Claude Code Codex Copilot CLI DeepSeek Gemini CLI opencode

🎯 Why

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.

πŸ“‘ Contents

πŸ“¦ Installation

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.py

The 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.

πŸš€ Quickstart

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.

🧭 Choosing a flow

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]
Loading

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]
Loading

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
Loading

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
Loading

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
Loading

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
Loading

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 --> [*]
Loading

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
Loading

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.

✨ Features

  • 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.

πŸ”§ Configuration

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.

πŸ“¦ Releases

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.

πŸ“š Documentation

πŸ“ Repository layout

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

πŸ”— Skill dependencies

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
Loading

🧰 Development

Run the repository checks from the clone root:

python tests/run-all.py

The 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.

πŸ” AI disclosure

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.

🀝 Contributing

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.

πŸ“„ License

MIT, copyright 2026 Andrei Gramakov.

πŸ“ˆ Status

Actively maintained, with automated checks on pushes and pull requests. CI checks scripts and packaging; behavioral reliability requires separately executed agent evaluations.

About

AI workflow allowing to develop and understand, not just vibe-code

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages