Agent Guidelines

Agent Execution Rules

Agents must follow the standards in README.md before taking any action. These rules tighten the workflow for autonomous execution.

• No changes without a Taskboard issue. All non-read-only work must be tied to a Taskboard issue before starting work. Create the issue first, then begin implementation.
  • Read-only work (no ticket required): Code viewing, analysis, research, documentation reading, answering questions, providing reviews
  • Non-read-only work (ticket required): File edits, commits, PRs, branch creation, configuration changes, documentation updates
  • Issue state: Issue should be in appropriate state before work begins (e.g., refinement for planning, implementation for coding)
• Traceability required. Every change must be traceable to a Taskboard issue; create one if it does not exist.
  • Format: Reference issue in commit messages (Refs: #123), PR titles and descriptions, and issue comments with evidence links
  • Evidence: Link commits (SHA URLs), PRs, and verification results in issue comments
  • Mid-implementation: If work is discovered during implementation, create issue immediately before proceeding
• Applied-skill evidence required. Verification requirements differ based on change type:
  • Concrete changes (code, configuration, documentation files): Must include applied evidence showing the skill was actually used in THIS repository. Evidence must include commit SHAs and file links. Example: "TDD skill applied: failing test at [SHA1], implementation at [SHA2], passing test at [SHA3]"
  • Process-only (planning, reviews, requirements gathering): Analytical verification is acceptable. Evidence includes issue comment links and decision records. Must state: "This is analytical verification (process-only)." Example: "Brainstorming skill applied: requirements clarified in issue #123, alternatives considered, decision documented"
  • See BDD Checklist Templates for detailed guidance on both verification types.
• Feature branch only. If you are on main, stop and create a feature branch before any edits or commits. Do not commit on main.
• Baseline failure blocks work. On baseline verification failure, create or reference a blocking issue and pause the current task until baseline passes.
• Worktrees location. Use .worktrees/ as the preferred worktree directory unless instructed otherwise.
• Skills-first enforcement. Bootstrap, load skills, and follow process skills before any implementation.
• TDD enforcement. Apply the README TDD standard to ALL changes (code, configuration, documentation). For documentation and process work, capture and verify a failing BDD checklist before editing. BDD checklists serve as "tests" for non-code changes:
  • RED Phase: Write failing BDD checklist, verify it fails, commit before changes
  • GREEN Phase: Implement changes, verify checklist passes, document evidence
  • See BDD Checklist Templates for concrete vs process-only verification patterns. TDD applies equally to documentation as it does to code - no "verify after" changes allowed.
  • Bug Fix TDD Workflow: When a bug is discovered during implementation, follow this strict sequence:
    1. STOP - Do not fix immediately, even if the fix seems obvious
    2. Write failing test - Create a test that reproduces the bug
    3. Verify test fails - Confirm the test fails with the current code
    4. Commit failing test - Record the RED phase with evidence
    5. Implement fix - Make the minimum change to fix the bug
    6. Verify test passes - Confirm the fix resolves the issue
    7. Commit fix - Record the GREEN phase with evidence This applies even when the fix is trivial - the test documents the bug and prevents regression.
• Fallback stays compliant. If handing off to a human, the same skills-first workflow still applies.
• PR close policy. Follow the README merge policy (rebase, then choose squash or fast-forward only) and use a Conventional Commit squash message with ticket footer when appropriate.
• Autonomous PR checklist. Post the checklist comment below on every autonomous PR and enable auto-merge once required approvals and checks pass.

## Summary

- <what changed and why>

## Issues

- Refs: #<issue-number>
- Closes #<issue-number>

## Test plan

- [ ] `<command>` ([evidence](link))

## Verification

- <verification evidence or link>

## Auto-merge

- [ ] Enable auto-merge after required approvals and checks pass

• Issue closure after scope complete. When all in-scope work for an issue is delivered (all required PRs merged), post final evidence comment and close the issue. If issue requires multiple PRs, keep open until all scope delivered or remaining work moved to new ticket. Do not leave issues open after all work complete.

Taskboard Workflow

All non-read-only work follows a standard issue lifecycle with required evidence at each stage:

Issue Lifecycle:

1. New Feature / Bug / Enhancement (Initial state)
   • Issue created with title, description, and acceptance criteria
   • Tagged appropriately (component, work type, priority)
   • Ready for refinement
2. Refinement (Planning phase)
   • Self-assign when starting refinement
   • Create implementation plan on feature branch
   • Commit plan with SHA reference
   • Post plan link to issue for approval
   • Wait for explicit approval comment
   • Stay assigned during approval feedback loop
   • Unassign after approval received
3. Implementation (Execution phase)
   • Self-assign when ready to implement
   • Follow approved plan
   • Commit changes with issue references (Refs: #123)
   • Post progress updates and evidence to issue
   • Create sub-tasks if work is complex
   • Unassign after implementation complete
4. Verification (Quality assurance phase)
   • Self-assign when ready to verify
   • Run tests, verify acceptance criteria met
   • Post verification evidence to issue (test output, screenshots, etc.)
   • Request role-based reviews if applicable
   • Address any critical issues found
   • Unassign after verification complete
5. Complete (Closed)
   • All PRs merged
   • Final evidence comment posted with links to PRs and commits
   • Acceptance criteria verified as met
   • Issue closed
   • Auto-unassigns on close

State Transition Rules:

• Always transition issue state when moving between phases
• Post evidence comment when transitioning states
• Self-assign when taking ownership of a phase
• Unassign when phase complete to enable pull-based coordination

Evidence Requirements:

Each state transition requires specific evidence posted to issue comments:

• Refinement → Implementation: Link to approved plan (commit SHA URL)
• Implementation → Verification: Links to commits, PRs, implementation evidence
• Verification → Complete: Links to test results, review approvals, merged PRs

Implementation Skills:

The baseline taskboard requirement can be implemented using:

• Full workflow: development-skills:issue-driven-delivery (comprehensive issue-driven process with plans, approvals, sub-tasks, and reviews)
• Agent automation: development-skills:agent-workitem-automation (automated agent interaction with taskboard and step updates)

These skills build on the mandatory baseline established in this section.

Bootstrap (First-Time Setup)

If this is your first time in this repository, install prerequisites before loading skills:

1. Install Superpowers (if not already installed):
   • Follow: https://github.com/obra/superpowers#installation
   • Verify: Check that ~/.claude/superpowers or ~/.codex/superpowers exists
2. Install development-skills (this repository):
   • Option A (Symlink): Clone elsewhere and symlink to skills directory (recommended for development). See README.md Installation section.
   • Option B (Direct): Clone directly to skills location:
     • Claude: ~/.claude/skills/development-skills
     • Codex: ~/.codex/skills/development-skills
3. Verify skills are discoverable:
   • Agent should auto-detect skills from standard locations
   • Test by attempting to load development-skills:skills-first-workflow

After bootstrap is complete, follow the Prerequisites First workflow below.

Documentation Standards for Agents

Human-Centric Documentation Principle

Skill names are agent implementation details. When documenting, always use human-readable terminology.

Documentation Mapping

When applying skills, document in human-centric locations:

Exclusions and Opt-Outs

Before suggesting any pattern/practice:

1. Check docs/exclusions.md for existing opt-outs
2. If pattern is excluded with matching scope, DO NOT re-prompt
3. Only mention if context has changed significantly (and note that briefly)

When user opts out of a pattern:

1. Update docs/exclusions.md with:
   • Human-readable pattern name (primary)
   • Agent skill mapping (for agent reference)
   • Reason, date, scope
   • When to reconsider
2. Use human terminology in the entry
3. Keep it concise (1-3 sentences)

Exclusions vs ADRs:

• Exclusions: Declined patterns/practices → docs/exclusions.md (concise)
• ADRs: Major architectural/tooling decisions → docs/adr/ (detailed with alternatives)

Documentation Requirements

Keep README.md and AGENTS.md concise:

• Reference detailed docs, don't duplicate
• Use standard InnerSource/OpenSource structure
• Aggregate related information in human-readable docs

When skills apply patterns:

1. Update appropriate human-centric doc (architecture-overview.md, coding-standards.md, etc.)
2. Use industry terminology, not skill names
3. If creating new major pattern, consider ADR for the decision
4. Don't create skill-specific documentation files

Example: When architecture-testing skill identifies clean architecture pattern:

# In docs/architecture-overview.md

## Architectural Pattern

This project follows Clean Architecture with clear boundary enforcement:

**Layers:**

- Domain (core business logic)
- Application (use cases, orchestration)
- Infrastructure (external concerns)
- Presentation (UI, API)

**Dependency Rules:**

- Dependencies point inward only
- Domain has no external dependencies
- Automated enforcement via NetArchTest in CI

**Testing:**

- Architecture tests validate boundaries in `tests/Architecture.Tests/`
- Tests fail build if dependencies violated

Not: "architecture-testing skill applied with clean architecture configuration"

Progressive Document Loading

Agents SHOULD load document frontmatter first, then full content only when needed. This reduces context consumption and improves selection accuracy.

Progressive Loading Principle

Load frontmatter first, full content when relevant. Frontmatter contains summary fields sufficient for selection and applicability decisions. Only load full document body when execution or detailed rationale is required.

Summary Fields by Document Type

For complete field definitions and validation rules, see the respective README files.

When Frontmatter Suffices

Use frontmatter only when:

• Selecting which document applies to current context
• Checking applicability of a role, decision, or playbook
• Building lists of relevant documents for a task
• Quick reference to a decision or trigger condition

When Full Document Needed

Load the full document body when:

• Executing a playbook requires details beyond the summary
• Understanding rationale for why a decision was made
• Following step-by-step procedures with nested steps or decision points
• Reviewing alternatives that were considered (ADRs)
• Learning capabilities of a role beyond its description

Loading Algorithm

1. Scan frontmatter of all documents in the relevant directory
   • Use Read tool with limit: 20 to capture frontmatter block
   • Frontmatter ends at closing --- delimiter (typically lines 1-15)
2. Filter by matching triggers, descriptions, or status (for ADRs)
3. Select the most applicable document(s) using conflict resolution rules
4. Execute using summary fields if sufficient
5. Load body only if summary references details not provided
   • Use Read without limit for full document content

Cross-References

For detailed guidance on each document type:

• Roles: See docs/roles/README.md - frontmatter schema and selection
• ADRs: See docs/adr/README.md - status semantics and agent workflow
• Playbooks: See docs/playbooks/README.md - trigger matching and progressive disclosure workflow

Prerequisites First

Before any task or response in this repo (after bootstrap):

1. Load development-skills:skills-first-workflow to enforce workflow.
2. Ensure Superpowers is installed and bootstrapped.
3. Load superpowers:using-superpowers.
4. Load any other relevant skills for the task.

Skills-First Default Workflow

The default in this repo is skills-first, not implementation-first. Do not start coding or editing files until the skills workflow is active.

The development-skills:skills-first-workflow skill enforces this workflow:

1. Verifies Superpowers is installed and bootstrapped (AutoFix if not).
2. Verifies superpowers:using-superpowers is loaded (AutoFix if not).
3. Verifies AGENTS.md exists and is current (AutoFix if not).
4. Ensures process skills are loaded before implementation:
   • superpowers:brainstorming (for unclear requirements or new features)
   • superpowers:writing-plans (for multi-step tasks)
   • superpowers:test-driven-development (for code changes)
   • superpowers:verification-before-completion (always)
5. Blocks implementation until all verifications pass.

If autonomous execution is blocked or uncertain, hand off to a human but keep the skills-first workflow intact. Human-driven fallback still requires the same skills and guardrails.

No Implementation First

Jumping straight into implementation is an exception and must be explicitly requested by the user. The default is to load and apply skills before any repo actions.

Superpowers Skills Integration

This repository integrates with Superpowers for process skills. The relationship is complementary:

What Superpowers Provides (Process Skills)

• superpowers:test-driven-development - TDD process guidance (RED/GREEN/REFACTOR workflow)
• superpowers:verification-before-completion - Verification process before claiming completion
• superpowers:brainstorming - Requirements clarification and design exploration
• superpowers:writing-plans - Implementation planning guidance
• superpowers:receiving-code-review - Code review reception process

These are process-only skills that guide workflow without modifying repository files.

What This Repository Provides (Concrete Requirements)

• BDD Checklist Templates - Concrete vs process-only verification patterns
• Verification Requirements - When to use applied evidence vs analytical verification
• Issue-Driven Workflow - Work item tracking and evidence requirements
• Agent Automation - Autonomous work item management

These define concrete requirements for this repository's workflow.

How They Work Together

1. TDD Workflow: Superpowers provides TDD process, this repo requires BDD checklists
   • Superpowers: "Write test first (RED), implement (GREEN), refactor"
   • This repo: "Create failing BDD checklist, implement, verify passing"
   • Integration: Both apply - code uses TDD, documentation uses BDD checklists
2. Verification: Superpowers provides verification process, this repo defines verification types
   • Superpowers: "Verify before claiming complete"
   • This repo: "Use concrete verification for file changes, analytical for process-only"
   • Integration: Superpowers enforces verification, this repo defines how to verify
3. Evidence: No conflict - complementary requirements
   • Superpowers: Ensures verification happens
   • This repo: Defines what verification evidence looks like (commit SHAs vs comment links)

No Conflicts Identified

• Superpowers skills are process guidance (analytical verification)
• This repo's skills may be concrete (issue-driven-delivery, markdown-author) or process-only
• Superpowers never requires commit evidence (process-only)
• This repo only requires commit evidence for concrete changes
• All Superpowers skills use analytical verification when applied in this repo

References

• BDD Checklist Templates: docs/references/bdd-checklist-templates.md
• Superpowers Repository: https://github.com/obra/superpowers

Skill Authoring Standards

Self-Containment Principle

A skill folder is a self-contained deployable unit. Skills must not reference artifacts outside their folder.

Required:

• All references must be to files within skills/<skill-name>/
• Use references/ subfolder for supporting documentation
• Describe external concepts generically (e.g., "team roles in your repository's docs/roles/ directory") rather than linking outside the skill

Prohibited:

• References to ../../docs/ or other paths outside the skill folder
• Links to repository-specific artifacts that may not exist when skill is deployed elsewhere
• Assumptions about repository structure beyond the skill folder

Platform-Agnostic vs Repo-Specific

Skills should be platform-agnostic (supporting GitHub, Azure DevOps, Jira, etc.). Repository-specific artifacts are generated during bootstrap or deployment:

When deploying a skill to a repository:

1. Skill's references/ content is platform-agnostic (covers all platforms)
2. Repo's docs/playbooks/ should be platform-specific (only the platform used by the repo)
3. Choose between:
   • Symlink: If skill reference requires no customization for the repo's platform
   • Customized copy: If repo needs platform-specific content only (recommended)

Customized playbook guidelines:

• Include ONLY the platform used by the repo (e.g., GitHub-only for GitHub repos)
• Remove all other platform examples (no Azure DevOps/Jira in a GitHub repo playbook)
• Reference the skill's platform-agnostic version for complete coverage
• Keep playbook concise - it's a quick reference, not comprehensive docs

Skill Folder Structure

skills/<skill-name>/
├── SKILL.md                    # Main skill documentation
├── <skill-name>.test.md        # BDD tests for skill behavior
├── references/                 # Supporting documentation
│   ├── <topic>.md             # Reference docs (self-contained)
│   └── ...
└── scripts/                    # Reference scripts (if applicable)
    └── ...

Checklist for Skill Authors

Before publishing or committing a skill:

• No ../../ references in SKILL.md or reference docs
• All links point to files within skill folder
• External concepts described generically, not linked
• Platform-specific examples cover GitHub, Azure DevOps, and Jira where applicable
• BDD tests exist for skill behavior

Canonical Skill Priority Model

Skills can be classified into the following priorities:

• P0 – Safety & Integrity: security, immutability, provenance, traceability, data integrity.
• P1 – Quality & Correctness: behavioural correctness, clean builds, contract stability, test validity.
• P2 – Consistency & Governance: repository conventions, versioning discipline, pipeline conformance.
• P3 – Delivery & Flow: incremental execution, developer experience improvements.
• P4 – Optimisation & Convenience: ergonomics and non-critical improvements.

Conflict resolution

1. Higher priority wins.
2. If equal priority: prefer narrower scope.
3. If scope equal: prefer stronger guardrails.

Multi-Skill Application

A single task may require the application of multiple skills. It is the responsibility of the agent (or human) to:

• Identify the complete set of relevant skills before starting execution.
• Analyze how these skills interact and identify any conflicts.
• Resolve conflicts as per the "Conflict Resolution" process

Skill Structure

• README.md describes the purpose and prerequisites for developing skills.
• New skill specs and supporting assets should live in clearly named top-level folders (for example, skills/skill-name/ with a short README.md).
• Skills should be progressively loaded, keep non-critical detail and examples in focused documents within a references/ folder with the skill and reference the file from the main SKILL.md.
• If in doubt refer to the agentskills.io specification
• Keep any shared reference documents in the top level docs/ folder

Prerequisite Repositories

Skills in this repository depend on external skill libraries. Install these before using skills from this repo:

• Superpowers: https://github.com/obra/superpowers
  • Follow installation and bootstrap instructions for your agent
• development-skills: https://github.com/mcj-coder/development-skills
  • This repository (install per your agent's skill installation mechanism)

Superpowers Bootstrap

Superpowers is the source of truth for the skill library.

• CRITICAL: Do not proceed with any task until Superpowers has been installed, bootstrapped, and you've applied the using-superpowers skill.
• Follow the installation instructions in the Superpowers repository for your specific agent.
• Use your agent's default skill locations and loading mechanisms.

Agent-Specific Instructions

• Keep skills interoperable with superpowers and document any integration assumptions.
• Update README.md when adding a new skill or changing prerequisites.