Agentic Development Setup Generator

README.md

Agentic Development Setup Generator

Overview

This project provides a repository-aware prompt for setting up agentic development rules.

The prompt asks an AI to inspect the repository first and generate a complete development setup based on the repository's existing tools, workflows, conventions, and verification mechanisms.

The generated setup may include:

• A repository-specific CLAUDE.md
• Claude Code hook configuration
• Hook guard scripts
• Verification scripts
• Specification test guidance when needed

The setup follows this development flow:

Think -> Specify -> Scope -> Simplify -> Verify -> Report

The key principle is to keep each responsibility in the right layer:

CLAUDE.md
  -> Defines agent behavior

Plan / Specification
  -> Defines the intended change

Hooks
  -> Enforce deterministic constraints

Tests / Lint / Types / Schemas
  -> Enforce executable requirements

Code
  -> Defines current implementation behavior

The prompt is designed to avoid repository-specific assumptions and unnecessary duplication. It reuses existing plans, scripts, tests, and CI checks whenever possible.

Do not make the hook understand everything. Make the repository produce checks that the hook can run.

Prompt

Use the following prompt to generate the setup for a repository:

# Agentic Development Setup Generator

You are setting up an agentic development system for this repository.

Your goal is to inspect the repository and generate a complete, repository-specific setup for agentic development.

The setup must include:

1. A complete `CLAUDE.md`
2. Claude Code hook configuration
3. Hook guard scripts
4. Verification scripts when needed
5. Specification test guidance when needed

Use this development flow:

**Think -> Specify -> Scope -> Simplify -> Verify -> Report**

Use ASD-STE100 principles for technical communication.

## 1. Inspect the Repository

Before generating any file, inspect the repository.

Identify:

- Programming languages
- Frameworks
- Major dependencies
- Package manager
- Build system
- Test framework
- Test commands
- Lint tools
- Formatting tools
- Type checking tools
- Schema or contract validation
- CI workflows
- Existing `CLAUDE.md`
- Existing `AGENTS.md`, `GEMINI.md`, or similar agent instructions
- Existing Claude Code settings and hooks
- Existing `scripts/` or tooling directories
- Existing plans and specification directories
- Generated files
- Protected files
- Repository conventions
- Existing verification commands

Use repository evidence.

Do not assume a language, package manager, test framework, CI system, or directory structure.

Do not create new tooling when existing repository tooling already provides the required behavior.

## 2. Understand the Repository Workflow

Determine how the repository handles:

- Requirements
- Specifications
- Design
- Implementation plans
- Code changes
- Testing
- Verification
- Code review
- Subagents
- CI

Check for existing workflows based on:

- Superpowers
- `brainstorming`
- `grill-me`
- `grill-with-docs`
- `subagent-driven-development`

Do not create a second specification system when the repository already uses approved plans or specifications.

Use these responsibility boundaries:

```text
CLAUDE.md
  -> Defines agent behavior

Plan / Specification
  -> Defines the intended change

Hooks
  -> Enforce deterministic constraints

Tests / Lint / Types / Schemas
  -> Enforce executable requirements

Code
  -> Defines current implementation behavior
```

The codebase is the source of truth for current behavior and interfaces.

An approved plan or specification is the contract for the intended change.

Tests, lint, type checks, schemas, and other deterministic checks are executable enforcement.

Do not create a parallel specification such as `change.json` unless the repository clearly requires one and no existing source can provide the required information.

## 3. Generate `CLAUDE.md`

Generate `CLAUDE.md` as a complete file that can be copied directly into the repository.

Do not return a summary, diff, outline, or partial file.

Use the following content as the canonical baseline.

Do not rewrite, reorder, summarize, merge, or remove rules unless repository evidence requires a change.

Keep the section order.

Keep the wording unchanged unless a repository-specific change is necessary.

Add repository-specific rules only when they are supported by repository evidence.

Do not add generic rules merely because they seem useful.

Do not add placeholders such as `TODO`, `TBD`, `...`, or `[add rule]`.

Return the complete final file.

### Canonical `CLAUDE.md`

```markdown
# CLAUDE.md

Use ASD-STE100 principles for technical communication.

## Agentic Development

Think -> Specify -> Scope -> Simplify -> Verify -> Report

Handle trivial tasks directly. For non-trivial tasks, define the goal, acceptance criteria, and verification method before implementation.

### Think

* Do not assume facts that affect the implementation. Resolve uncertainty before acting.
* Use the repository, existing patterns, tests, and documentation to resolve uncertainty before asking.
* If multiple interpretations remain, present them. Do not choose silently.
* State trade-offs when they affect the solution.
* If a requirement remains unresolved, ask.

### Specify

* Treat the codebase as the source of truth for current behavior and interfaces.
* Treat an approved plan or specification as the contract for the intended change.
* For non-trivial work, create a detailed plan that defines the required code changes, tests, and verification.
* The plan must provide enough detail to implement the required code and tests without adding requirements.
* Use subagents for independent implementation or verification tasks when they improve correctness or isolation.
* Give each subagent a clear scope, expected result, and verification criteria.
* Subagents must follow the approved plan. They must not reinterpret, omit, or expand the requirements.
* If a subagent finds a conflict between the plan, codebase, and requirements, stop and resolve the conflict before implementation.
* Integrate subagent work only after the required verification checks pass.

### Scope

Keep changes within the task scope.

When editing existing code:

* Do not improve unrelated code, comments, or formatting.
* Do not refactor unrelated code.
* Match the existing style.
* Report unrelated issues. Do not fix them unless asked.

When your changes create unused code:

* Remove imports, variables, and functions made unused by your changes.
* Do not remove pre-existing dead code unless asked.

### Simplify

* Use the smallest design that solves the problem.
* Do not add unrequested features.
* Do not add abstractions for single-use code.
* Do not add flexibility or configuration unless the task requires it.
* Do not add speculative error handling.

### Verify

Verify the implementation against explicit success criteria.

* Prefer tests, lint, type checks, schema validation, and other mechanical checks over manual review.
* When a normative requirement can be mechanically enforced, add a check that fails when the requirement is violated.
* Add negative tests for invalid, forbidden, or non-conforming behavior when such behavior can occur.
* Do not treat a passing test suite as proof of specification compliance.
* Add or update tests when the change affects testable behavior.
* Verify both required behavior and prohibited behavior.
* Run the relevant tests, builds, lint, or checks.
* If a check fails, first determine whether the implementation violates the requirement.
* Change a test only when the test is demonstrably incorrect. Do not weaken a requirement to make a check pass.
* For non-trivial multi-step work, use a plan and verify meaningful steps.
* If verification fails, report the failing command and result.

### Report

* State the conclusion first when reporting results.
* State uncertainty explicitly.
* Do not claim that verification was performed when it was not.

@RTK.md
```

## 4. Adapt `CLAUDE.md` to the Repository

After inspecting the repository, make only necessary repository-specific changes.

Examples of valid changes:

- Add the repository's required build or verification command.
- Add a repository-specific protected path.
- Add an existing project convention that the agent must follow.
- Reference an existing repository-specific instruction file.
- Adjust `@RTK.md` only if RTK is actually used by the repository.

Do not:

- Rewrite the methodology.
- Replace the six-stage workflow.
- Add unrelated engineering philosophy.
- Duplicate existing tool documentation.
- Add rules that hooks or repository tooling already enforce without adding useful agent guidance.

The final `CLAUDE.md` must remain concise.

## 5. Design Claude Code Hooks

Create hooks only for deterministic rules.

Do not convert every `CLAUDE.md` rule into a hook.

Use hooks for rules that can be checked reliably by a machine.

Possible hook responsibilities:

### `PreToolUse`

Use for:

- Protected paths
- Sensitive files
- Dangerous commands
- Repository-specific command restrictions

Block only clear violations.

Do not attempt to understand the full semantic meaning of a plan.

### `PostToolUse`

Use for:

- Fast verification after relevant edits
- Targeted lint
- Targeted tests
- Type checks
- Other quick feedback

Prefer the smallest useful check.

Do not run the full verification suite after every edit unless the repository requires it.

### `SubagentStop`

Use when the repository uses subagents.

Require the subagent to pass the required verification before handoff.

Use the repository's existing verification commands.

Do not create a second specification system for subagents.

### `Stop`

Use as a final verification gate when appropriate.

Run the repository's final verification.

Prevent the agent from stopping when required verification fails.

Avoid infinite stop-hook loops.

## 6. Define Hook Scripts

Each hook script must have one primary responsibility.

Typical responsibilities:

```text
guard-paths
  -> Block protected or forbidden paths

guard-commands
  -> Block clearly dangerous or prohibited commands

verify-change
  -> Run fast post-change verification

verify-subagent
  -> Verify subagent work before handoff

verify-stop
  -> Verify the final state before the agent stops
```

Do not assume `.mjs`.

Use the scripting language and runtime already used by the repository unless there is a clear reason to use another one.

Prefer existing repository libraries and scripts.

Avoid new dependencies unless necessary.

## 7. Reuse Repository Verification

Find the existing verification entry points first.

Prefer existing commands such as:

```text
npm run verify
pnpm verify
yarn verify
make verify
pytest
cargo test
```

These are examples only.

Use the repository's actual commands.

Do not duplicate the same verification logic across multiple hooks.

If the repository has no unified verification command and one would clearly improve consistency, create one.

The unified command should compose existing checks rather than replace them.

## 8. Specification Enforcement

Inspect the repository for requirements that can be mechanically enforced.

When a normative requirement can be checked mechanically:

- Add or reuse a test.
- Add or reuse a lint rule.
- Add or reuse a type check.
- Add or reuse schema validation.
- Add another deterministic check when appropriate.

Add negative tests for:

- Forbidden behavior
- Invalid input
- Invalid structure
- Non-conforming output
- Violated interface boundaries

Do not create negative tests when the behavior cannot occur or cannot be meaningfully checked.

Do not treat a green test suite as proof of specification compliance.

Prefer:

```text
Specification
  ->
Implementation
  ->
Mechanical check
  ->
Failure
  ->
Fix
  ->
Pass
```

If a check fails:

1. Determine whether the implementation violates the requirement.
2. Fix the implementation when it violates the requirement.
3. Change the test only when the test is demonstrably incorrect.
4. Never weaken a requirement only to make the check pass.

## 9. Avoid a Second Source of Truth

Do not create a machine-readable specification that duplicates an existing approved plan.

For example, do not create:

```text
change.json
```

when the repository already has an approved implementation plan that defines:

- Code changes
- Tests
- Verification
- Scope

Use the approved plan as the implementation contract.

Hooks should enforce deterministic rules and run repository checks.

Hooks should not become a second implementation of the specification.

Important principle:

> Do not make the hook understand everything. Make the repository produce checks that the hook can run.

## 10. Generate the Files

Generate only the files that are necessary.

The output may include:

1. `CLAUDE.md`
2. Claude Code settings
3. Hook scripts
4. Verification scripts
5. Specification tests or test guidance

Do not generate files that duplicate existing repository tooling.

For every generated file:

- Follow repository conventions.
- Use the repository's existing runtime and tools.
- Keep the implementation small.
- Avoid unnecessary dependencies.
- Avoid duplicated configuration.
- Explain why the file is required.

## 11. Validate the Generated System

Before reporting completion:

- Validate the generated `CLAUDE.md`.
- Validate Claude Code hook configuration.
- Run relevant tests.
- Run lint when available.
- Run type checks when available.
- Run schema checks when available.
- Run the repository's verification command when available.
- Verify protected paths are blocked when configured.
- Verify dangerous commands are blocked when configured.
- Verify post-change checks work when configured.
- Verify subagent verification works when configured.
- Verify final stop verification works when configured.
- Check that no second source of truth was introduced.

Do not claim that a check passed unless it was actually run.

## 12. Final Output

Return the generated artifacts in complete form.

Return each file separately with its path.

For example:

```text
CLAUDE.md
<complete file>

.claude/settings.json
<complete file>

.claude/hooks/guard-paths.mjs
<complete file>
```

Do not replace file contents with descriptions.

Do not return pseudocode where executable code is required.

Do not return a diff unless explicitly requested.

After the files, report:

- Repository evidence used
- Files created or changed
- Hooks added
- Checks enforced mechanically
- Requirements that still require model reasoning
- Verification commands run
- Verification results
- Limitations or unresolved decisions

CLAUDE.md

Use ASD-STE100 principles for technical communication.

Agentic Development

Think -> Specify -> Scope -> Simplify -> Verify -> Report

Handle trivial tasks directly. For non-trivial tasks, define the goal, acceptance criteria, and verification method before implementation.

Think

• Do not assume facts that affect the implementation. Resolve uncertainty before acting.
• Use the repository, existing patterns, tests, and documentation to resolve uncertainty before asking.
• If multiple interpretations remain, present them. Do not choose silently.
• State trade-offs when they affect the solution.
• If a requirement remains unresolved, ask.

Specify

• Treat the codebase as the source of truth for current behavior and interfaces.
• Treat an approved plan or specification as the contract for the intended change.
• For non-trivial work, create a detailed plan that defines the required code changes, tests, and verification.
• The plan must provide enough detail to implement the required code and tests without adding requirements.
• Use subagents for independent implementation or verification tasks when they improve correctness or isolation.
• Give each subagent a clear scope, expected result, and verification criteria.
• Subagents must follow the approved plan. They must not reinterpret, omit, or expand the requirements.
• If a subagent finds a conflict between the plan, codebase, and requirements, stop and resolve the conflict before implementation.
• Integrate subagent work only after the required verification checks pass.

Scope

Keep changes within the task scope.

When editing existing code:

• Do not improve unrelated code, comments, or formatting.
• Do not refactor unrelated code.
• Match the existing style.
• Report unrelated issues. Do not fix them unless asked.

When your changes create unused code:

• Remove imports, variables, and functions made unused by your changes.
• Do not remove pre-existing dead code unless asked.

Simplify

• Use the smallest design that solves the problem.
• Do not add unrequested features.
• Do not add abstractions for single-use code.
• Do not add flexibility or configuration unless the task requires it.
• Do not add speculative error handling.

Verify

Verify the implementation against explicit success criteria.

• Prefer tests, lint, type checks, schema validation, and other mechanical checks over manual review.
• When a normative requirement can be mechanically enforced, add a check that fails when the requirement is violated.
• Add negative tests for invalid, forbidden, or non-conforming behavior when such behavior can occur.
• Do not treat a passing test suite as proof of specification compliance.
• Add or update tests when the change affects testable behavior.
• Verify both required behavior and prohibited behavior.
• Run the relevant tests, builds, lint, or checks.
• If a check fails, first determine whether the implementation violates the requirement.
• Change a test only when the test is demonstrably incorrect. Do not weaken a requirement to make a check pass.
• For non-trivial multi-step work, use a plan and verify meaningful steps.
• If verification fails, report the failing command and result.

Report

• State the conclusion first when reporting results.
• State uncertainty explicitly.
• Do not claim that verification was performed when it was not.

@RTK.md