From agentic-development-workflow
Pauses development to align human intent with agent output across quality dimensions like visual design, UX flow, API surface, or data model. Generates a dimension-specific brief then captures decisions into calibration artifacts.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agentic-development-workflow:calibrateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Human alignment checkpoint. Agents build to spec, but specs are lossy compressions of human intent. This skill pauses execution, lets the human inspect what was built, and captures what "right" actually means in a format agents can consume.
references/briefs/api-surface.mdreferences/briefs/copy-tone.mdreferences/briefs/data-model.mdreferences/briefs/performance-quality.mdreferences/briefs/scope-direction.mdreferences/briefs/ux-flow.mdreferences/briefs/visual-design.mdreferences/calibration-types.mdreferences/capture/api-surface.mdreferences/capture/copy-tone.mdreferences/capture/data-model.mdreferences/capture/performance-quality.mdreferences/capture/scope-direction.mdreferences/capture/ux-flow.mdreferences/capture/visual-design.mdreferences/design-brief-template.mdreferences/design-context-schema.yamlreferences/schemas/copy-tone-schema.yamlreferences/schemas/ux-flow-schema.yamlreferences/schemas/visual-design-schema.yamlHuman alignment checkpoint. Agents build to spec, but specs are lossy compressions of human intent. This skill pauses execution, lets the human inspect what was built, and captures what "right" actually means in a format agents can consume.
Where this fits:
/aep-reflect (identified alignment gap)
→ /aep-calibrate (Phase 1: generate dimension-specific brief)
→ human explores (method varies by type — external tools, conversation, code review)
→ /aep-calibrate capture (Phase 2: capture decisions into artifact)
→ /aep-dispatch (stories dispatched with calibration context)
Session: Main, interactive with user
Input: Calibration type + product definition from product/index.yaml (split mode) or product-context.yaml (v1 mode) + operational state from product-context.yaml
Output: Calibration artifact (standalone or inline) + updated calibration.history
Check how the skill was invoked to determine the calibration dimension:
Path A — Explicit: User says /aep-calibrate visual-design or /aep-calibrate api-surface. Type is given directly.
Path B — Routed from /aep-reflect: Reflection classified an observation as a calibration need with a specific dimension. The dimension and observation text are passed as context.
Path C — Ambient: User says /aep-calibrate with no type. Determine the type:
calibration.plan in product-context.yaml (operational file, both modes) — which dimension is next for the current layer?calibration_type set in the current .5 layer.ls product/index.yaml 2>/dev/null && echo "SPLIT MODE" || echo "V1 MODE"
cat product-context.yaml
product/index.yaml exists): Read quality_dimensions, layers, activities, constraints, success_criteria, failure_model from product/index.yaml. Read calibration.plan, calibration.history, stories, architecture from product-context.yaml.product-context.yaml.Write targets by calibration type:
calibration/<type>.yaml. Append calibration.history + changelog in product-context.yaml.architecture.interfaces or architecture.domain_model in product-context.yaml. Append calibration.history + changelog.product.goals, product.mvp_boundary, product.layers, product.success_criteria, or product.failure_model in product/index.yaml (split mode) or product-context.yaml (v1 mode). Append calibration.history + changelog in product-context.yaml.After type is determined, check for existing calibration:
calibration.history for this dimension → full brief, create artifact from scratchCalibration types split into two natural classes:
External exploration required. The human uses tools outside the agent workflow (design tools, wireframing, copy docs). Produces standalone YAML artifacts in calibration/ directory. Creates .5 alignment layer stories.
| Dimension | Brief Template | Exploration Method | Time Scale | Capture Artifact |
|---|---|---|---|---|
| visual-design | references/briefs/visual-design.md | External tool (Stitch, Pencil.dev) | Hours–days | calibration/visual-design.yaml |
| ux-flow | references/briefs/ux-flow.md | Conversation + optional wireframe tool | 30–60 min | calibration/ux-flow.yaml |
| copy-tone | references/briefs/copy-tone.md | Conversation + copy doc | 1–2 hours | calibration/copy-tone.yaml |
Conversational. The human reviews current state and makes decisions through structured Q&A. Updates existing sections of product-context.yaml directly. May or may not create .5 layer stories.
| Dimension | Brief Template | Exploration Method | Time Scale | Sections Updated |
|---|---|---|---|---|
| api-surface | references/briefs/api-surface.md | Conversation + code review | 30–60 min | architecture.interfaces |
| data-model | references/briefs/data-model.md | Conversation + schema review | 30–60 min | architecture.domain_model |
| scope-direction | references/briefs/scope-direction.md | Conversation | 30–60 min | product.goals, product.mvp_boundary, product.layers |
| performance-quality | references/briefs/performance-quality.md | Conversation + benchmarks | 30–60 min | product.success_criteria, product.failure_model |
cat product-context.yaml
Extract:
opportunity.bet + product.problem → product identityproduct.persona.description + product.persona.jtbd → target useropportunity.why_now → urgency/positioningstories where layer matches the active layer → scope of what was built or will be builtproduct.constraints.required_stack + preferred_stack → technical constraintscalibration.history → prior calibration decisions for this dimension (extension mode)Scan targets vary by calibration type:
| Type | Scan Targets |
|---|---|
| visual-design | globals.css (theme tokens), components/ (available components), routes/ (existing pages) |
| ux-flow | routes/ (existing pages), product.activities (journey backbone), stories (what was built) |
| api-surface | architecture.interfaces (contracts), existing API/route handler files, endpoint patterns |
| data-model | architecture.domain_model (entities), schema/migration files, ORM models |
| scope-direction | product.goals, product.mvp_boundary, stories by layer (built vs planned) |
| copy-tone | UI components with text content, product.persona, brand-related product context |
| performance-quality | product.success_criteria.non_functional, error logs, monitoring data if available |
Use the type-specific template from references/briefs/<type>.md.
Establishment mode: Generate the full brief template with all sections.
Extension mode: Read existing calibration artifact or product-context sections. Identify what's NEW in the current layer that isn't covered by prior calibration. Generate a focused brief: "Here's your current calibrated system. These new [pages/endpoints/entities/etc.] need decisions not yet covered: [list]."
Write the brief to docs/calibration-brief.md and output the full content to terminal.
Heavy calibrations (visual-design, ux-flow, copy-tone):
Output exploration instructions and stop. The human explores externally — this is explicitly out of the agent's hands.
Calibration brief written to: docs/calibration-brief.md
Next steps (you do these):
1. [Type-specific exploration instructions]
2. Explore variations. Pick what feels right.
3. Save reference files to docs/calibration-references/ (if applicable)
4. When ready, come back and run:
/aep-calibrate capture
For visual-design specifically, point to references/vibe-design-tools.md for tool guidance.
Light calibrations (api-surface, data-model, scope-direction, performance-quality):
Present the brief to the human, then proceed directly to Phase 2. No external exploration needed — the brief frames the conversation.
/aep-calibrate capture)Ask structured questions from references/capture/<type>.md, one at a time.
Heavy calibration questions (examples):
Light calibration questions (examples):
Heavy calibrations:
references/schemas/<type>-schema.yaml. Fill all sections from Q&A answers.calibration/<type>.yaml. Add new entries for newly covered patterns. Update calibrated_at and calibrated_from_layer. Do not replace existing values — extend them.Write to calibration/<type>.yaml.
Light calibrations:
Update the relevant section(s) — see File Resolution above for which file to write to per calibration type:
| Type | Section to Update |
|---|---|
| api-surface | architecture.interfaces — naming, grouping, error contracts |
| data-model | architecture.domain_model — entity names, fields, relationships |
| scope-direction | product.goals, product.mvp_boundary, product.layers |
| performance-quality | product.success_criteria.non_functional, product.failure_model |
For visual-design specifically: Also update globals.css with the captured palette. Read palette values, convert to oklch if provided in other color spaces, write as CSS custom properties under :root and .dark selectors.
Append to calibration.history in product-context.yaml:
- dimension: <type>
calibrated_at: "<ISO date>"
calibrated_from_layer: <layer>
mode: establishment # or extension
artifact_path: "calibration/<type>.yaml" # null for light calibrations
sections_updated: [] # e.g., ["architecture.interfaces"] for light calibrations
summary: "<one-line summary of what was decided>"
Also append to changelog:
- date: <ISO date>
type: calibration
author: human
summary: "Calibrated <dimension> — <summary of decisions>"
sections_changed:
- calibration
- <any other sections updated>
# Resolve $BASE (integration branch) — see git-ref "Integration Branch" (override → develop → main)
BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
[ -z "$BASE" ] && { git show-ref --verify --quiet refs/heads/develop \
|| git show-ref --verify --quiet refs/remotes/origin/develop; } && BASE=develop
BASE=${BASE:-main}
git pull --ff-only origin "$BASE"
git add calibration/ product-context.yaml
git commit -m "feat: calibrate <dimension> — <brief summary>"
git push origin "$BASE"
Visual design is the most fully developed calibration type and serves as the reference implementation for others.
references/briefs/visual-design.mdreferences/vibe-design-tools.md — covers Google Stitch, Pencil.dev, and alternatives.references/schemas/visual-design-schema.yamlcalibration/visual-design.yaml — palette (oklch), typography, spacing, layout, components, brand signals, reference designsglobals.css with CSS custom properties from captured palettecalibration/visual-design.yaml documents decisions (why), globals.css enacts them (what), reference files in docs/design-references/ show the visual target (how it looks).calibration/visual-design.yaml does not exist → full calibration (palette, typography, layout, everything)palette.dark.primary, components.border_radius, voice.personality). Prose descriptions are not queryable..5 layers are human alignment layers. Not just "UI polish." Any dimension where agent output diverges from human intent.npx claudepluginhub memorysaver/agentic-engineering-patterns --plugin agentic-development-workflowProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.