Bootstrap Agent Environment for my projects

bootstrap-agent.txt

You are an expert software architect and AI agent systems designer.

Your task is to **analyze this repository and generate a complete agent environment** for it — compatible with OpenCode, Claude Code, Codex, Gemini, or any AI agent.

---

## Phase 1: Discovery (do this first)

Explore the repository thoroughly before generating anything:

1. Scan all directories and files (structure, names, extensions)
2. Identify all technology stacks (languages, frameworks, runtimes, package managers)
3. Identify the layout: single-repo, monorepo, multi-repo, or standalone folder
4. Find config files: `package.json`, `*.csproj`, `pubspec.yaml`, `build.gradle`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `*.sln`, `*.pbxproj`, `*.rdl`, etc.
5. Identify external integrations, CI/CD pipelines, deployment targets
6. Identify domain entities, main features, and business purpose
7. Identify test frameworks, linting tools, and build commands
8. Note any existing agent/AI guidance files (`CLAUDE.md`, `AGENTS.md`, `COPILOT-INSTRUCTIONS.md`, `.cursorrules`, etc.)
9. If a frontend/UI exists, identify CSS variables, Tailwind config, theme files, design tokens, or stylesheets

Do NOT assume. Base everything strictly on what you find.

---

## Phase 2: Generate the Agent Environment

Generate **all of the following files**, adapted to what the repo actually is.
If a concept does not apply (e.g. no frontend, no design system), skip that file entirely.

---

### File 1: `AGENTS.md`

The main guidance file for any AI agent working in this repo.

Include:
- **Project overview** — what the system does in 2-4 sentences
- **Repository layout** — exact folder structure with purpose per folder
- **Tech stack** — per component/layer/app
- **Build & run commands** — copy-paste ready for dev, build, test, lint
- **Available agent skills** — table of skill name, location, purpose
- **Memory files** — key reference files agents should read for context
- **Guardrails**:
  - Security: secrets, credentials, API keys — what agents must never do
  - Git: commit/push/merge rules (human-only by default)
  - Scope: max files per change, forbidden areas (pipelines, infra, auth)
- **New agent task checklist** — step-by-step workflow for agents
- **Key conventions** — coding patterns, naming, architecture patterns found in the repo

---

### File 2: `ARCHITECTURE.md`

Analyze the architecture of this codebase with the goal of creating an ARCHITECTURE.md file in the project root and giving the user a file for easy copy & pasting.

Reference material:
  Website : https://architecture.md/
  Repo    : https://github.com/timajwilliams/architecture

Requirements:
- Create a complete ARCHITECTURE.md document that enables rapid codebase comprehension for both human developers and AI agents.
- The file must be entirely self-contained. Do not say "see X file" as a substitute for explanation; include the relevant architectural facts directly in the document.
- Be specific and concrete: include actual directories, important files, modules, services, classes, APIs, commands, data stores, configuration points, and integration boundaries where they are discoverable from the codebase.
- Do not invent systems, services, infrastructure, deployment targets, databases, queues, third-party APIs, or security mechanisms that are not supported by evidence in the repository.
- When something cannot be determined from the codebase, explicitly mark it as "Not evident from the repository" rather than guessing.
- Prefer durable architectural facts over transient implementation details. Focus on things that help someone understand where to make changes and how the system fits together.
- Include diagrams using Mermaid where helpful, especially for system context, component relationships, request/data flow, and deployment topology.
- If Mermaid is not appropriate or the architecture is simple, include a clear text-based diagram instead.
- If architecture decisions or tradeoffs are visible from the code, document the rationale and consequences.
- Include technical debt, risks, unclear boundaries, and future architecture considerations when supported by TODOs, comments, docs, issue references, or code structure.
- Use Markdown only. Do not rely on external images, generated assets, or links to local files.
- Write the document as if it will be committed to the repository and maintained over time.

Structure:

# Architecture Overview

Briefly describe what the system is, what problem it solves, who/what uses it, and the major architectural style or pattern if evident.

## 1. Project Structure

Provide a high-level annotated tree of the repository. Explain the purpose of each major directory and the architectural layer or concern it represents.

Include:
- Root-level files that affect architecture, build, runtime, deployment, or developer workflow
- Source directories and their responsibilities
- Test directories and their scope
- Configuration, scripts, generated code, migrations, schemas, or infrastructure directories if present

## 2. High-Level System Diagram

Provide a Mermaid diagram or text diagram showing the major actors, applications, services, data stores, and external systems.

The diagram should emphasize:
- User or client entry points
- Application/runtime boundaries
- Internal services or modules
- Data stores
- External APIs or platforms
- Direction of communication/data flow

## 3. Core Components

Describe each major component of the system.

For each component include:
- Name
- Responsibility
- Important files/directories
- Key technologies/frameworks
- Runtime role
- Main inputs and outputs
- Dependencies on other components
- Notes about ownership of business logic, state, or side effects

### 3.1 Frontend / User Interface

If present, document:
- Framework and rendering model
- Routing/page structure
- State management
- API/data access pattern
- Component organization
- Styling/design-system approach if architecturally relevant
- Build output and deployment assumptions

### 3.2 Backend / Server / API

If present, document:
- Framework/runtime
- Entry points
- Routing/controller structure
- Service/business-logic layer
- Persistence layer
- Middleware
- Authentication/authorization flow
- Background jobs/workers if present

### 3.3 Shared Libraries / Common Code

If present, document:
- Shared types
- Utilities
- Domain models
- Validation schemas
- Cross-cutting abstractions

### 3.4 CLI / Scripts / Automation

If present, document:
- Command entry points
- Build/test/deploy automation
- Code generation
- Data seeding/migration scripts

## 4. Data Flow

Explain how data moves through the system.

Include:
- Main request lifecycle
- Important user journeys or system workflows
- Read/write paths
- Validation boundaries
- Serialization/deserialization points
- Error handling paths
- Async/event-driven flows if present

Add a Mermaid sequence diagram for the most important runtime flow when possible.

## 5. Data Stores

List and describe all persistent or semi-persistent storage mechanisms evident in the codebase.

For each data store include:
- Name
- Type/technology
- Purpose
- Main schemas/tables/collections/entities if discoverable
- Ownership boundaries
- Migration or schema management approach
- Backup, retention, or lifecycle details if evident

If no persistent storage is evident, say so.

## 6. External Integrations / APIs

Document all external systems the codebase integrates with.

For each integration include:
- Service name
- Purpose
- Integration method (REST, GraphQL, SDK, webhook, OAuth, file import/export, message queue)
- Where it is configured or called
- Authentication method if evident
- Failure/retry behavior if evident

## 7. Key Technologies

Summarize the technical stack.

Include:
- Languages
- Frameworks
- Runtime/platform
- Package managers
- Build tools
- Testing tools
- Linters/formatters
- Infrastructure/deployment tools
- Observability tools
- Important libraries that shape the architecture

Explain why each technology matters architecturally, not just that it exists.

## 8. Deployment & Infrastructure

Describe how the system appears to be built, packaged, configured, and deployed.

Include:
- Build artifacts
- Environment variables/configuration model
- Containerization if present
- Hosting/deployment target if evident
- CI/CD workflows
- Infrastructure-as-code
- Runtime process model
- Scaling assumptions if evident

If deployment is not evident from the repository, state that clearly and summarize what would need to be known.

## 9. Security Architecture

Document security-relevant architecture.

Include:
- Authentication
- Authorization
- Session/token handling
- Secrets management
- Input validation
- Data encryption in transit/at rest if evident
- CORS/CSP/security headers if present
- Dependency or supply-chain security measures
- Trust boundaries
- Sensitive data handling

Do not claim security controls exist unless the codebase shows them.

## 10. Monitoring & Observability

Document how the system can be debugged and observed.

Include:
- Logging approach
- Metrics
- Tracing
- Error reporting
- Health checks
- Audit logs
- Debug tooling
- Operational dashboards or monitoring services if evident

If observability is minimal or absent, say so and identify the current gaps.

## 11. Performance & Scalability

Document performance-sensitive parts of the architecture.

Include:
- Caching
- Pagination
- Batching
- Background processing
- Database query patterns
- Asset optimization
- Concurrency model
- Known bottlenecks
- Scaling limits or assumptions

Only include claims supported by code, configuration, or documentation.

## 12. Development Workflow

Explain how developers work with the project.

Include:
- Local setup
- Required tools/runtime versions
- Install commands
- Development server commands
- Test commands
- Build commands
- Lint/format/typecheck commands
- Database setup/migrations if present
- Common development loops

Keep this section architecture-focused; do not duplicate a README unless the workflow affects system structure.

## 13. Testing Strategy

Describe the testing architecture.

Include:
- Test frameworks
- Unit/integration/e2e test locations
- Fixtures/mocks
- Test data strategy
- CI test execution
- Coverage or quality gates if evident
- Gaps in test coverage if inferable from the repository

## 14. Architectural Decisions & Rationale

Capture important architectural choices visible in the codebase.

For each decision include:
- Decision
- Evidence in the codebase
- Rationale if inferable
- Consequences/tradeoffs
- Alternatives if mentioned in docs/comments

Do not invent historical rationale. If rationale is unclear, say "Rationale not documented."

## 15. Constraints, Risks, and Technical Debt

Document:
- Architectural constraints
- Known limitations
- Tight coupling
- Duplicated abstractions
- Missing boundaries
- Incomplete migrations
- TODO/FIXME items with architectural impact
- Operational risks
- Security or scalability concerns

Each item should include why it matters and where the evidence appears in the codebase.

## 16. Future Considerations / Roadmap

Summarize future architectural changes that are evident from code comments, docs, TODOs, roadmap files, or incomplete abstractions.

Separate:
- Explicitly documented future work
- Reasonable architectural recommendations based on current structure

Clearly label recommendations as recommendations.

## 17. Project Identification

Include:
- Project name
- Repository purpose
- Primary language(s)
- Application type
- Main runtime(s)
- Date of last architecture review
- Maintainer/team if evident

Use today's date for "Date of last architecture review."

## 18. Glossary / Acronyms

Define project-specific terms, acronyms, domain concepts, and internal names that a new developer or AI agent needs to know.

Validation pass before finalizing:
- Verify every named component, service, data store, integration, and technology against the repository.
- Remove placeholders.
- Remove generic template text.
- Replace vague statements with concrete codebase-specific facts.
- Ensure every major source directory is represented somewhere in the document.
- Ensure the high-level diagram matches the written component descriptions.
- Ensure the document is useful to someone trying to answer: "Where do I make a change, and what will it affect?"
- If access to a running local server, tests, build output, generated docs, API schema, database schema, Docker environment, or screenshots is available, use them to validate and revise the architecture description.

---

### File 3: `DESIGN.md` _(only if a UI/frontend exists — skip entirely otherwise)_

Analyze the design system of this codebase with the goal of creating a DESIGN.md file in the project root and giving the user a file for easy copy & pasting.

Reference material:
  Overview : https://stitch.withgoogle.com/docs/design-md/overview/
  Format   : https://stitch.withgoogle.com/docs/design-md/format/
  Spec     : https://github.com/google-labs-code/design.md

Examples from the spec repo:
  https://github.com/google-labs-code/design.md/blob/main/examples/atmospheric-glass/DESIGN.md
  https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md

Requirements:
- Begin with YAML frontmatter containing all structured design tokens
  (colors, typography, spacing, elevation, motion, radii, shadows, etc.)
- Follow with free-form Markdown that describes the look & feel and
  captures design intent that token values alone cannot convey
- The file must be entirely self-contained — do not reference any
  files, variables, or paths from the codebase
- All token values must use valid YAML design token format
- Extract actual values from existing CSS variables, Tailwind config,
  theme files, design tokens, or stylesheets found in the repository
- If access to a running local server or screenshots of the product is
  available, compare your DESIGN.md against the rendered UI. Revise
  until both the YAML tokens and the written description faithfully
  capture the product's visual identity

---

### File 4: `.opencode/skills/agent-triage/SKILL.md`

A triage skill that analyzes the codebase and identifies impacted files for a given change.

Include:
- Frontmatter: `name`, `description`, `license`, `compatibility`
- **Capabilities** specific to this repo's structure
- **How to scan** — exact paths to check per layer/component (adapted to actual structure)
- **Risk assessment** (low/medium/high) — file count thresholds adapted to repo size
- **Output format** — structured template:
  ## Triage Analysis
  **Task:** <description>
  **Affected Files:** <list>
  ### Direct Files
  - <file> - <reason>
  ### Dependent Files
  - <file> - <reason>
  ### Risk Assessment
  - Scope: <low/medium/high>
  - Files: <count>
  ### Recommendation
  <proceed/reject - with reason>
- **Scope limits** — max files, forbidden areas
- **Example scenarios** — 2 realistic examples from this repo's domain
- **Interaction rules** — triage only, never implement

---

### File 5: `.opencode/skills/agent-implementation/SKILL.md`

An implementation skill that writes code following the repo's conventions.

Include:
- Frontmatter: `name`, `description`, `license`, `compatibility`
- **Role**: writes code changes based on triage output
- **How to implement**: step-by-step (read triage output → understand context → write changes → self-verify)
- **Conventions to follow** — actual patterns found in the codebase (naming, structure, architecture)
- **Code examples** — small realistic snippets following actual repo patterns
- **What NOT to do** — anti-patterns or forbidden actions specific to this repo
- **Output format** — file path + full file content (preferred) or unified diff
- **Interaction rules** — always based on triage output, never modify pipelines/infra/auth

---

### File 6: `.opencode/skills/agent-review/SKILL.md`

A review skill that checks code changes for quality, correctness, and convention compliance.

Include:
- Frontmatter: `name`, `description`, `license`, `compatibility`
- **Role**: review proposed changes without implementing anything
- **Review checklist** adapted to the repo's stack and patterns:
  - Correctness
  - Convention compliance (actual patterns from this repo)
  - Security
  - Tests presence/adequacy
  - Scope adherence (within triage boundaries)
- **Risk flags** — specific things to flag in this repo
- **Output format** — structured review:
  ## Review Result
  | Category | Status | Notes |
  |----------|--------|-------|
  | Correctness | PASS/FAIL | ... |
  | Conventions | PASS/FAIL | ... |
  | Security | PASS/FAIL | ... |
  | Tests | PASS/FAIL | ... |
  | Scope | PASS/FAIL | ... |
  ### Overall: APPROVE / REQUEST CHANGES
  <summary>
- **Interaction rules** — review only, never modify files

---

### File 7: `openspec/specs/{project-name}/spec.md`

A project spec for AI agents with BDD-style requirements.

Include:
- **Purpose** — why this spec exists for agents
- **Requirements** using `SHALL` language with BDD scenarios:
  - Project structure understanding (which repo/folder for which concern)
  - Domain knowledge (key entities and relationships)
  - Tech stack awareness (correct tool per component)
  - Code conventions (actual patterns found)
  - Pipeline respect (pipelines are off-limits)
  - Git guardrails (commit/push/merge = human only)
- **Project overview** — domain entities, main routes/endpoints, tech stack summary
- **Key directories** — exact paths per component
- **Commands** — build, test, lint, run per component
- **Architecture patterns** — the ones actually found in the codebase
- **Entity relationships** — if a domain model is present, include a simple tree or diagram

---

## Phase 3: Output

For each file:
1. State the file path clearly (e.g. `### AGENTS.md`)
2. Output the full file content in a code block
3. Add a one-line note on what was inferred vs. found directly

Rules:
- **Do not produce generic filler.** Every file must reflect the actual repository.
- If something cannot be determined, add a `<!-- TODO: fill in -->` placeholder with a note explaining what is missing and why.
- If a file does not apply to this repository (e.g. no frontend = no DESIGN.md), state that clearly and skip it.
- Adapt all skill files to the actual directory structure, tech stack, and domain of this repository.