agent instruction forge

Data Community

Skill notes

Seven Properties of a Great Rule

Specific & falsifiable — agent can verify compliance. Unfailable = not a rule. "Write clean code" → "Every external API call must return Result<T, AppError>, never throw." Encodes WHY — without rationale, agents optimize around rules. "Don't use console.log" → "Use src/lib/logger.ts — console.log bypasses Datadog correlation IDs." Born from real failure — past pain produces specificity.

Rules Should NOT Contain

Things fixable in code (better type signature, clearer name, linter rule) Things linting already enforces Language documentation (agent knows the language) Obvious patterns derivable from reading the code Aspirational rules nobody follows (document reality unless explicitly marked aspirational)

PHASE 1 — Codebase Discovery (Automated)

Read codebase before asking anything. Don't ask what code already answers.

Step 1: Discover instruction infrastructure

Scan: AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, .github/instructions/*.instructions.md, .github/prompts/*.prompt.md, .context/, .ctx, README.md, ARCHITECTURE.md, CONTRIBUTING.md, ADR dirs, formatter/linter configs, tsconfig/pyproject.toml, Makefile/justfile, CI/Docker configs. For each file: topics, staleness, format/tone.

Step 2: Codebase topology

Map: languages, frameworks, package managers, directory structure (2-3 levels), entry points, test structure, external integrations.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Data
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Docker
Runtime requirements
Docker
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
PHASE 1 — Codebase Discovery (Automated)

Read codebase before asking anything. Don't ask what code already answers.

02
Step 1: Discover instruction infrastructure

Scan: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `.github/prompts/*.prompt.md`, `.context/`, `.ctx`, `README.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`, ADR dirs, formatter/linter configs, `tsconfig`/`pyproject.toml`, `Makefile`/`justfile`, CI/Docker configs. For each file: topics, staleness, format/tone.

03
Step 2: Codebase topology

Map: languages, frameworks, package managers, directory structure (2-3 levels), entry points, test structure, external integrations.

04
Step 3: Pattern extraction

Sample 3-5 files from most-modified directories (`git log --stat` or inferred from size/complexity). Detect: naming, error handling, import organization, logging, test patterns.

05
Step 3b: History mining (if git/PR available)

`git log` for reverts, migrations, convention enforcement, hotfixes — each encodes an implicit rule. Keywords: convention, instead, revert, breaking, deprecated, don't. PR access (`gh pr list --state merged --limit 30`): scan review corrections ("nit:", "use X instead"), architectural rationale in descriptions, repeated feedback. Capture: source, candidate rule, category (C1-C9), confidence. If unavailable: ask in Phase 2: "Patterns you correct repeatedly in reviews but aren't documented?"

06
Step 4: Rule Audit (Augment Mode Only)

For each existing rule: Seven Properties Score (0-7). Flag <=2. P1 failure (specific/falsifiable) = noise regardless of other scores. Code Alignment: Confirmed | Stale | Aspirational | Contradicted | Unverifiable Coverage: C1 Architecture, C2 Domain/Business, C3 Conventions, C4 Integrations, C5 Operations, C6 Testing, C7 Security, C8 Performance, C9 Historical Decisions Redundancy: duplicated by lint/types/CI? Contradicts other rules?

07
Step 5: Discovery Brief

Greenfield: target system, what code reveals, top candidate rules from history, highest-value gaps Augment: rule health summary, top issues, undocumented rules from history, coverage gaps Verify: any "remove" rules actually important? "Confirmed" rules outdated? Which history-surfaced rules are real conventions? Which gaps matter most?

08
PHASE 2 — Knowledge Extraction (Interactive)

2-4 questions per round. Don't dump 20. In Augment mode, weave three workstreams: Verify flagged rules: "This rule says [X]. Still accurate?" Fill coverage gaps: skip well-covered categories, focus on empty ones Strengthen weak rules: "Why? What goes wrong otherwise?" / "File that best exemplifies this?"

09
PHASE 3 — Synthesis

PHASE 3 — Synthesis

10
PHASE 3b — Adversarial Validation

Before showing rules, stress-test with three isolated subagents receiving ONLY the synthesized file. Read `references/adversarial-validation.md` for prompts. Run in parallel: Newcomer — finds gaps Prior Override — checks rules beat common training priors Contradiction Finder — finds conflicts and ambiguities

11
PHASE 4 — Review & Delivery

Present rules. Iterate on feedback. Write to target: System · Files Copilot · `.github/copilot-instructions.md` (repo-wide) + `.github/instructions/NAME.instructions.md` (scoped) + `.github/prompts/NAME.prompt.md` Claude Code · `CLAUDE.md` (root + subdirs)

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.