agentsope/SkillAlchemy / skills/agentsop-repo-state-gating
agentsop-repo-state-gating
VerifiedA 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.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.3 KB |
| SKILL.md | skill md | 15.3 KB |
| intermediate/operation_candidates.json | config | 6.3 KB |
| references/R1-state-taxonomy.md | markdown | 6.6 KB |
| references/R2-gate-questions.md | markdown | 7.6 KB |
references/R2-gate-questions.md
View on GitHub# R2 — The 5-Question Gate and Decision Tree
This is the actual gate. It runs in ≤ 60 seconds once you've memorized it.
## Pre-gate (three commands, ~15 seconds)
```bash
git log --oneline | wc -l # N_commits
git ls-files | wc -l # N_tracked
ls -la # top-level shape
```
Optional fourth: `git log --since='90 days ago' --oneline | wc -l` (recent activity).
Optional fifth: `git shortlog -sn | wc -l` (contributor count).
These numbers feed Q1.
## The 5 questions
### Q1 — Size
> `git ls-files | wc -l` … is it under 20?
- **A** (under 20): no symbol surface to lean on
- **B** (20+): symbol surface exists
The 20 threshold is generous on the low side; for monorepos, run Q1 inside the subdirectory you're working in.
### Q2 — Public API
> Does this code have **external consumers**? (Published to a registry, depended on by other repos, has a CHANGELOG with semver entries.)
- **A** (no): internal application or prototype
- **B** (yes): library/SDK — public surface matters
If Q2=B, **state = library-SDK regardless of other answers**. Library status dominates because the *behavior change cost* is qualitatively different (breaking external callers).
### Q3 — Familiarity
> Can you name the top 5 modules / packages **from memory**, without opening the repo?
- **A** (no): unfamiliar — you'd have to grep to find auth, models, etc.
- **B** (yes): familiar — you have a mental map
For an *agent*, the analogous question is "is there a CLAUDE.md / AGENTS.md / README that maps the architecture in <100 lines?" If yes and the agent has read it this session, treat as familiar.
### Q4 — Typical change scope
> A normal task touches how many files?
- **A** (1–3): focused changes
- **B** (4+): cross-cutting changes
This is a proxy for whether `/add` discipline buys you anything. Cross-cutting changes hit context budget faster and benefit more from repo-map.
### Q5 — Written conventions
> Is there a `CONVENTIONS.md` / `STYLE.md` / `CLAUDE.md` / `AGENTS.md` — or even a strict linter config the team treats as canonical?
- **A** (no): conventions are implicit or absent
- **B** (yes): conventions are written down
If Q5=B and Q1=B, you have a brownfield with installed guardrails — agent can use them.
## Decision tree
```
┌────────────────────┐
│ Q2: public API? │
└─────────┬──────────┘
B (yes) │ A (no)
│
┌──────────┴──────────┐
│ │
┌──────▼─────┐ ┌─────▼──────┐
│ Library/SDK│ │ Q1: <20 │
└────────────┘ │ files? │
└─────┬──────┘
A │ B
│ │ │
┌────────┘ │ └───────────┐
│ │ │
┌──────▼─────┐ │ ┌──────▼─────┐
│ Greenfield │ │ │ Q3: know │
└────────────┘ │ │ layout? │
│ └─────┬──────┘
│ B │ A
│ │ │ │
│ ┌────────┘ │ └──────────┐
│ │ │ │
│ │ ┌──────▼─────┐ ┌─────▼──────┐
│ │ │ Q4: 1-3 │ │ Brownfield │
│ │ │ files? │ │ large │
│ │ └─────┬──────┘ └────────────┘
│ │ A │ B
│ │ │ │ │
│ │ ┌────┘ │ └────────────┐
│ │ │ │ │
│ │ │ ┌──────▼─────┐ ┌──────▼─────┐
│ │ │ │ Mid-size │ │ Brownfield │
│ │ │ │ familiar │ │ large │
│ │ │ └────────────┘ └────────────┘
```
## Quick-lookup table (alternative to the tree)
| Q2 | Q1 | Q3 | Q4 | → State |
|----|----|----|----|---------|
| B | - | - | - | Library / SDK |
| A | A | - | - | Greenfield |
| A | B | A | - | Brownfield-large |
| A | B | B | A | Mid-size-familiar |
| A | B | B | B | Brownfield-large (cross-cutting → behave as if unfamiliar) |
Q5 doesn't change the state — but it **changes the first action**:
- Q5=A → first action in any state except greenfield is *write a 50-line CONVENTIONS.md*.
- Q5=B → first action is `/read CONVENTIONS.md` and respect what's there.
## Multi-state / monorepo handling
For `monorepo/packages/foo/`, repeat the gate **inside the subdirectory**:
```bash
cd packages/foo
git ls-files . | wc -l # subtree files
git log --oneline -- . | wc -l # subtree commits
ls -la
```
Different sub-packages can legitimately have different states. The agent should switch strategy when cwd changes.
For Aider specifically, use `--subtree-only` to scope repo-map to the cwd. For Claude Code, just `cd` and trust cwd discipline.
## What to do with the answer
Once you have a state, the SKILL.md §4 operations table tells you:
- which tool to launch
- which context primitive to enable (repo-map / scaffolder / docstring)
- how much autonomy to grant
- the file/token budget
Write one line into chat or notes:
```
[repo-state: brownfield-large @ 2026-05-19] tool=Aider, primitive=repo-map, autonomy=approve, budget=5 files/<25k tok
```
Future sessions: read this line, skip re-gating, save 5 minutes.
## When to re-gate
- More than a week since last gate AND the repo doubled in size
- New contributor joined
- You published v0.1.0 (greenfield/familiar → library)
- The agent has chosen wrong tools twice in a row (signal: state assumption is off)
- You merged a structural refactor
## References
- aider-sop-skill SKILL.md §3 Phase 1–2 (the bootstrap pattern this gate slots before)
- aider.chat/docs/troubleshooting/edit-errors.html (25k token threshold informs Q4 budget)
- BMAD method (gate-first project ritual)
- thegeneralpartnership.substack.com/p/a-practical-guide-to-brownfield-ai (familiarity question framing)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |