Getting Started

Create the directory structure

Your agentic layer needs two directories. Run this from your project root:

mkdir -p agentic-layer/{prompts,gates}

prompts/ holds your phase prompt templates. gates/ holds your quality gate criteria. You can add tools/, commands/, and workflow.yaml later.

agentic-layer/
+-- prompts/          # One template per workflow phase
|   +-- plan.md       # You'll write this in Step 2
|   +-- build.md      # You'll write this in Step 3
+-- gates/            # Quality criteria
    +-- test-pass.md  # You'll write this in Step 4

Write your Plan template

The Plan template tells your agent how to research and plan before writing any code. This is the first template to get right because it addresses the most common agent behavior: starting to build before fully understanding the problem.

Copy this entire file into agentic-layer/prompts/plan.md:

# 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)

Here's what each pattern does:

• Role assignment gives the agent a persona with clear boundaries. A "Software Architect" researches; it doesn't build.
• Template variables like ${issue_description} and ${issue_type} get replaced with real values when you run the workflow.
• Read-only constraint prevents the agent from building during planning. The read-only constraint keeps the agent in research mode during planning, preventing premature implementation.
• Anti-scope-creep explicitly states what is out of scope. Without this, agents love to "improve" things you didn't ask for.
• Structured output creates machine-readable sections that the Build phase can consume. This is artifact chaining.

Write your Build template

The Build template tells your agent how to implement the plan. Notice it references ${plan_artifact}. This is artifact chaining, where the output of one phase becomes the input of the next. The Plan output flows directly into Build.

Copy this into agentic-layer/prompts/build.md:

# Build Phase -- Software Engineer

## Role
You are a Software Engineer. Implement the plan
exactly as specified.

## Context
Plan: ${plan_artifact}
Issue: ${issue_description}

## Constraints
- Follow the plan. Do not add features, refactor
  unrelated code, or deviate from the spec.
- Write tests FIRST, then implementation.
- Only modify files listed in the plan.
- Make atomic, focused changes.

## Output
1. Tests written (file paths)
2. Implementation changes (file paths)
3. Commands to run tests
4. Any assumptions or deviations from plan (explain why)

• Artifact chaining: ${plan_artifact} links Build to the Plan output. The agent doesn't start from scratch; it starts from the plan.
• TDD-first: tests before implementation. The tests become the contract that every later phase validates against. This is a core framework principle.
• Scope lock: only files listed in the plan. No improvising, no "while I'm here" refactors.

Write your first quality gate

A quality gate, meaning pass/fail criteria that must be met before a phase completes, is your safety net. Your first gate is simple: do the tests pass?

Copy this into agentic-layer/gates/test-pass.md:

# Test Pass Gate

## Criteria
- All existing tests pass (zero failures)
- All new tests written by the Build phase pass
- No test was deleted or skipped to achieve a pass

## Pass
All criteria met. Proceed to next phase.

## Fail
One or more criteria not met.
Action: Feed test output + build template back to the
agent for a retry. Maximum 3 retries before escalating
to human.

Notice the Fail section defines what happens next. This is the beginning of a self-healing feedback loop. Instead of stopping on failure, the workflow retries with context about what went wrong.

Run your first workflow, manually

Now you'll run the Plan → Build → Test loop by hand. Pick a small, real issue from your project: a bug fix, a minor feature, or a simple task. Something you'd normally spend 30 minutes on.