Agentsop Repo State Gating

What it does

When your agent uses it

• Tasks that involve Codebase onboarding

Example prompts

• “/agentsop-repo-state-gating”

Requirements

• Python 3
• Node.js

Workflow steps

7 steps, taken from the step headings in SKILL.md.

1. 1何时激活
2. 2核心心智模型
3. 3SOP 工作流（5 步，每步 ≤30 秒）
4. 4操作模型（8 个 ops）
5. 5困境决策案例
6. 6反模式与边界
7. 7跨框架对照（同一状态 × 不同工具的最佳实践）

What it can do on your machine

Read from SKILL.md and the folder at commit d0f0355. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • git
  • npx
  • cargo
  • uv

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use git, npx and uv, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Agentsop Repo State Gating loads about 2.7k tokens when it runs, and up to ~6.3k if it reads all its reference files. Until then it costs about 162 tokens; SKILL.md has 745 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~162

When it runs · the whole SKILL.md, loaded when a task matches

~2.7k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~6.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from agentsope/SkillAlchemy at commit d0f0355, republished under its MIT licence (© agentsope). 745 words, ~2,701 tokens.

name

agentsop-repo-state-gating

description

A 5-minute gate the coder runs at project kickoff (and again whenever the repo shape changes). Classifies the workspace into Greenfield / Brownfield-large / Mid-size-familiar / Library-SDK, then maps the state to an agent strategy (autonomy, context primitive, tool choice). Use BEFORE picking Cursor vs Claude Code vs Aider, BEFORE turning on repo-map, BEFORE writing the first prompt. Skip only if the same repo was gated within the last day and nothing changed. Search keywords: greenfield vs brownfield, new project vs existing codebase, project setup strategy, legacy codebase agent, where to start a coding agent.

version

0.1.0

domain

coder-agent meta-strategy

audience

coder-agents (Claude Code / Cline / Cursor / Aider) and the humans driving them

source

aider-sop R4, dify-sop A6 escape-hatch, dspy-sop M3 compile-gate, BMAD greenfield/brownfield, GSD codebase-map, The Brownfield Problem (jjmasse 2026)

状态                  | 关键约束          | 最大杠杆            | 风险
----------------------+-------------------+---------------------+-------------------
Greenfield            | 没有现成符号      | LM 自治 + scaffolder| 过度设计、目录漂移
Brownfield-large      | 上下文炸 + 风格僵 | repo-map + 严格 /add| 修错文件、违反约定
Mid-size-familiar     | 你脑里有图        | 最小上下文 + /ask   | 多加文件稀释信号
Library / SDK         | 你的代码即 API    | 约定 + test-fix 环  | 破坏向后兼容

git log --oneline | wc -l          # 提交数
git ls-files | wc -l               # 跟踪文件数
ls -la                              # 顶层结构（package.json? pyproject? README? src/?）

Q1=A 且 Q5=A                              → Greenfield
Q2=B（公共 API 存在）                       → Library / SDK
Q1=B 且 Q3=A（不熟）                       → Brownfield-large
Q1=B 且 Q3=B（熟）且 Q4=A                  → Mid-size-familiar
其他                                       → Brownfield-large 兜底（最保守）

[repo-state: brownfield-large] tool=Aider, primitive=repo-map, autonomy=approve-each,
add-budget=2-5 files (<25k tok), convention=CONVENTIONS.md required.

op-1  gate-classify
  trigger: 新会话进入仓库
  rule: 跑 §3 Step 1 三命令 + §3 Step 2 五题 → 输出四态之一

op-2  greenfield-strategy
  trigger: state=greenfield
  rule:
    - 工具: Claude Code / Cursor / 纯 LLM 对话；不要 Aider（repo-map 空）
    - 原语: scaffolder 优先（create-next-app, cargo new, uv init, cookiecutter）
    - 自治: 中-高；让 LM 一次产出多文件骨架
    - 范围: 不限；但每生成 ~10 文件就 commit 一次

op-3  brownfield-large-strategy
  trigger: state=brownfield-large
  rule:
    - 工具: Aider（repo-map 是核心杠杆） / Claude Code（长上下文兜底）
    - 原语: 符号索引 / repo-map / ctags / tree-sitter；先 /ask 再 /code
    - 自治: 低；每个 tool-call / 编辑都 approve
    - 范围: /add 严格控制在 2–5 文件 + <25k tokens [aider edit-errors troubleshooting]
    - 必读: CONVENTIONS.md（不存在就先建）

op-4  mid-size-familiar-strategy
  trigger: state=mid-size-familiar
  rule:
    - 工具: Aider --architect 或 Claude Code（你脑里有图，工具只是杠杆）
    - 原语: 你给定文件 + /read 约定文件；不浪费 repo-map 预算
    - 自治: 中；/ask 先讨论方案，/code 再动手
    - 范围: 1–3 文件，单次 commit

op-5  library-sdk-strategy
  trigger: state=library-sdk
  rule:
    - 工具: Aider --auto-test 或 Claude Code with test runner
    - 原语: test-fix 闭环最高价值；docstring 自动生成；semver 检查
    - 自治: 低；改公共 API 必须人工确认
    - 范围: 不只看本仓 — 同时看 CHANGELOG / migration guide
    - 必备: 写 CONVENTIONS.md（API 命名风格、错误模式、deprecation 节奏）

op-6  state-reclassify
  trigger: 跑了一周后仓库形态明显变了；或工具一直选错
  rule: 重跑 op-1；如状态升级（greenfield→brownfield）则把第一行结论改写

op-7  cross-repo-multi-state
  trigger: monorepo / 多包仓库
  rule:
    - 不跑整仓 gate，跑子目录 gate（cd packages/foo && 跑 op-1）
    - 不同子目录可以有不同状态；agent 进入子目录时切策略
    - Aider 用 --subtree-only；Claude Code 用 cwd 限定

op-8  state-mismatch-rescue
  trigger: 已经开干，发现状态判错
  rule:
    - 立刻 /clear 或新会话，按对的状态重启
    - 不要"将就着用"——错状态下省的 5 分钟 < 错工具浪费的 1 小时

© agentsope, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (references) in skills/agentsop-repo-state-gating of agentsope/SkillAlchemy.

• SKILL.md
• README.md
• intermediate/operation_candidates.json
• references/R1-state-taxonomy.md
• references/R2-gate-questions.md

Open the folder on GitHubat commit d0f0355