Skip to main content

Adopt / Customization

Customization guide

The defaults get you started. Customization makes the framework yours. Everything here builds on the templates from Getting Started.

Adapting templates to your codebase

The Getting Started templates are intentionally generic. To make them work for your project, add four things: project structure context, language-specific constraints, team conventions, and domain knowledge.

Before and after: Plan template

Here's the generic Plan template from Getting Started compared to a customized version for a React + TypeScript project. Toggle between them to see what changed.

# Plan Phase -- Software Architect

## Role
You are a Software Architect. Research the codebase
and produce a detailed implementation plan.

## Context
Issue: ${issue_description}
Type: ${issue_type}

## Constraints
- Read-only. Do not modify any files.
- Research before planning. Read relevant source files,
  tests, and documentation before proposing changes.
- Reference specific file:line locations.
- Do NOT plan changes beyond the stated issue.

## Output
1. Summary of changes (2-3 sentences)
2. Files to modify (with line numbers)
3. Files to create (if any)
4. What we are NOT doing (anti-scope-creep)
5. Test strategy (what tests prove this works)
# Plan Phase -- React/TypeScript Architect

## Role
You are a Senior React/TypeScript Architect. Research
the codebase and produce a detailed implementation plan.

## Context
Issue: ${issue_description}
Type: ${issue_type}
Branch: ${branch_name}

## Project Structure                         # NEW
- Frontend: React 18 + TypeScript 5 + Vite
- State: Zustand for global, React Query for server
- Styling: Tailwind CSS + shadcn/ui components
- Testing: Vitest + React Testing Library + Playwright
- API: REST endpoints in /src/api/, types in /src/types/

## Constraints
- Read-only. Do not modify any files.
- Research before planning. Read relevant source files,
  tests, and documentation before proposing changes.
- Reference specific file:line locations.
- Do NOT plan changes beyond the stated issue.
- Follow existing component patterns in /src/components/ # NEW
- All new components must be typed -- no 'any' types.  # NEW
- Prefer composition over inheritance.                  # NEW
- All user-facing text must use i18n keys from /src/i18n/# NEW

## Output
1. Summary of changes (2-3 sentences)
2. Files to modify (with line numbers)
3. Files to create (if any)
4. What we are NOT doing (anti-scope-creep)
5. Test strategy:                                       # EXPANDED
   - Unit tests (Vitest + RTL)
   - Integration tests (if API changes)
   - E2E tests (Playwright, if user flow changes)
6. Accessibility impact (WCAG 2.1 AA compliance)        # NEW

What to add to your templates

Role specialization

Change "Software Architect" to "React/TypeScript Architect" or "Python Backend Architect."

Project structure

Add a section listing your stack, directory layout, and key dependencies. This gives the agent a map of your codebase before it starts exploring.

Architectural patterns

Document your conventions: naming, file organization, state management approach. "Follow existing component patterns in /src/components/" beats "write clean code."

Domain output sections

Add output sections for your domain: accessibility impact, performance budget, security considerations, i18n requirements. Each section becomes a checkpoint you can review.

Adding custom phases

Add a custom phase when you have a recurring step that doesn't fit the defaults, needs its own quality gate, and works better with a dedicated agent persona. Here's a full example: adding a security audit phase.

1

Create the template

Save this as agentic-layer/prompts/security-audit.md:

# Security Audit Phase -- Security Engineer

## Role
You are a Security Engineer. Audit the code changes
for security vulnerabilities, data exposure risks,
and authentication/authorization issues.

## Context
Code changes: ${build_artifact}
Test results: ${test_results}
Issue: ${issue_description}

## Constraints
- Read-only. Do not modify any files.
- Focus only on security concerns, not style or performance.
- Reference OWASP Top 10 where applicable.
- Classify findings by severity: critical, high, medium, low.

## Audit Checklist
- [ ] Input validation on all user-facing endpoints
- [ ] No hardcoded secrets, tokens, or credentials
- [ ] SQL/NoSQL injection vectors checked
- [ ] XSS vectors checked (if frontend changes)
- [ ] Authentication flows not weakened
- [ ] Authorization checks present on new endpoints
- [ ] Sensitive data not logged or exposed in errors
- [ ] Dependencies scanned for known vulnerabilities

## Output
1. Findings (severity, location, description, fix suggestion)
2. Passed checks (what was verified and looks good)
3. Verdict: PASS (no critical/high findings) or FAIL
2

Create the gate

Save this as agentic-layer/gates/security-audit.yaml:

gate: security-audit
criteria:
  - no_critical_findings: true
  - no_high_findings: true
  - all_checklist_items_reviewed: true
pass:
  action: proceed_to_next_phase
fail:
  action: escalate_to_human
  reason: "Security findings require human review"
  # Security failures never auto-retry -- always escalate
3

Update workflow.yaml

Insert the new phase into your workflow between Review and Document:

phases: [plan, build, test, review, security-audit, document, deploy]
loops:
  test_retry: { max: 3, on_exhaust: escalate }
  review_patch: { max: 2, on_exhaust: escalate }
gates:
  test: { all_pass: true }
  review: { max_blockers: 0 }
  security-audit: { max_blockers: 0, on_fail: escalate }

That's the full pattern: template + gate + workflow entry. You can add any phase this way (performance testing, accessibility audit, compliance review, database migration validation). Same three-file structure every time.

Custom agent roles

A role combines a persona, tool permissions, and an output format. When you need an agent to do something specific and repeatable, create a role for it. Three examples:

Database migration specialist

Persona: DBA with schema design expertise. Permissions: Read + Execute (for dry-run migrations). Output: migration SQL, rollback SQL, data impact assessment.

Read Execute Write

API contract validator

Persona: API design reviewer. Permissions: Read-only. Output: breaking change detection, versioning recommendations, OpenAPI spec diff.

Read Execute Write

Accessibility auditor

Persona: WCAG specialist. Permissions: Read + Execute (for running axe-core). Output: WCAG 2.1 AA compliance report, remediation priorities.

Read Execute Write

Issue-type routing

Different work needs different templates. A bug fix follows a different workflow path than a new feature. Issue-type routing lets you configure which templates, gates, and phases apply to each type of work.

Default routing

Issue Type Workflow Notes
feature All 7 phases Full workflow. Thorough planning and review.
bug All 7 phases Plan focuses on root cause analysis.
task All 7 phases Standard flow for refactoring, chores.
patch Build, Test, Deploy Skip Plan (scope already known). Lightweight.

Adding custom types

To add types like hotfix, migration, refactor, or spike, configure routing in your workflow.yaml:

routing:
  feature:
    phases: [plan, build, test, review, document, deploy, monitor]
    templates: { plan: prompts/plan-feature.md }
  bug:
    phases: [plan, build, test, review, document, deploy]
    templates: { plan: prompts/plan-bug.md }
  patch:
    phases: [build, test, deploy]
    gates: { test: { all_pass: true } }
  hotfix:
    phases: [build, test, deploy]
    loops: { test_retry: { max: 1, on_exhaust: escalate } }
    gates: { test: { all_pass: true } }
  migration:
    phases: [plan, build, test, review, security-audit, deploy]
    templates: { build: prompts/build-migration.md }
  spike:
    phases: [plan]
    # Spike produces a plan only -- no code changes
    gates: {}

Notice that spike runs only the Plan phase. It produces research and a recommendation, not code. And hotfix limits retries to 1. If the fix doesn't work immediately, escalate to a human. Routing lets you encode your team's judgment about how different work should flow.

CI/CD integration

The framework produces artifacts at each phase. Your CI/CD pipeline validates them. Here's how they connect.

Artifact flow

Phase Artifact CI/CD Integration
Plan Implementation spec Optional: attach to issue as comment
Build Code changes + tests Commit to feature branch
Test Test results + coverage Your CI runs the same tests independently
Review Review verdict + issues Post as PR review comments
Document Docs + changelog Include in PR description
Deploy Pull request CI validates, human or auto-merge

Integration patterns

PR-driven workflow

The workflow creates a PR. Your CI runs on the PR (tests, lint, build). CI passes, human reviews (or auto-merge at L4). Simplest integration. Works with any CI tool.

Event-driven triggering

A new issue gets created (or labeled). A webhook triggers the agentic workflow. The workflow runs Plan through Deploy. A PR appears. This is the L3+ pattern for teams that have earned the trust.

Team-specific overrides

For organizations with multiple teams, the base agentic layer has the shared defaults. Each team adds overrides for their stack and conventions. Team templates replace base templates for the same phase. Team gates are additive (they stack on top of base gates).

Directory pattern

agentic-layer/
+-- prompts/              # Base templates (org-wide defaults)
|   +-- plan.md
|   +-- build.md
|   +-- test.md
|   +-- review.md
+-- gates/                # Base gates
|   +-- test-pass.yaml
|   +-- review-pass.yaml
+-- teams/
|   +-- frontend/         # Frontend team overrides
|   |   +-- prompts/
|   |   |   +-- plan.md   # Replaces base plan.md
|   |   |   +-- build.md  # Replaces base build.md
|   |   +-- gates/
|   |       +-- a11y.yaml # Additive: runs in addition to base
|   +-- backend/          # Backend team overrides
|   |   +-- prompts/
|   |   |   +-- plan.md
|   |   +-- gates/
|   |       +-- api-contract.yaml
|   +-- data/             # Data team overrides
|       +-- prompts/
|       |   +-- build.md
|       +-- gates/
|           +-- migration-safety.yaml
+-- workflow.yaml

workflow.yaml teams config

teams:
  frontend:
    override_dir: teams/frontend
    merge_strategy:
      prompts: replace    # Team plan.md replaces base plan.md
      gates: additive     # Team a11y.yaml runs in addition to base gates
  backend:
    override_dir: teams/backend
    merge_strategy:
      prompts: replace
      gates: additive
  data:
    override_dir: teams/data
    merge_strategy:
      prompts: replace
      gates: additive

When to use overrides: use overrides when teams have different stacks (frontend vs. backend), different domain constraints (fintech compliance vs. internal tools), or different quality requirements. If every team would use the same template, keep it in the base layer. Overrides should be the exception, not the default.