Agents & Skills

AI agent definitions and workflow skills for TDD-driven development with human-in-the-loop.

Purpose

Provides specialized agents and workflows for:

• Feature development — Plan → TDD cycles → Commit → Document
• Bug fixing — Investigate → Reproduce → Test → Fix
• Code hardening — Test coverage, refactoring, deterministic validation

Designed to work with human operators, not autonomously.

Principles

• Single responsibility — Each agent owns one task
• Human-in-the-loop — Approval required between phases
• Micro-edit protocol — One change → verify → report → wait
• Tests as specification — Code must satisfy tests, nothing more
• Direct communication — No praise, no filler, facts only

Adding Agents

1. Create agent file manually in your CLI tool (Claude Code, Factory AI, etc.)
2. Copy the main prompt from agents/<agent-name>.md
3. Copy the description from the YAML frontmatter
4. Choose model:
   • GLM-4.7-Opus → use Opus or heavy model
   • GLM-4.5-Sonnet → use Sonnet or medium model
   • GLM-4.5-Air-Haiku → use Haiku or light model
5. Approve only necessary tools available in your CLI

Adding Skills

1. Create .claude/skills/ or .factory/skills/ folder if it doesn't exist
2. Copy skill folders directly from skills/

Invoking Agents & Skills

Agents: Invoked automatically by primary agent based on task, or request explicitly:

• "Use the coverage-hardener agent to analyze test coverage"
• "Launch the review-agent to verify this implementation"

Skills: Referenced automatically by agents, or direct the agent:

• "Follow the tdd-workflow skill"
• "Use the deterministic-hardening skill to check project setup"

Best Practices

Be Specific

Every cycle has complexity. Success depends heavily on the human operator. Use targeted, specific prompts — don't make the agent guess.

Stay Engaged

These workflows require active human participation:

• Review edits before approving
• Interrupt and add comments
• Provide details and context
• Do your own research and share findings

Manage Context

• After each feature cycle, agents archive context files
• Compress/summarize chat and bring summary to new session
• Saves tokens and keeps agent focused
• Start completely new sessions for new sprints

Session Hygiene

• One sprint = one session when possible
• Summarize learnings before ending session
• New sprint = fresh session with clean context

Current Workflows

Workflow	Phases	Use Case
feature-cycle	Plan → [TDD → Commit]* → Archive → Document	New features
tdd-workflow	Red → Green → Review → Refactor	Single acceptance criterion
bug-fix-cycle	Investigate → Reproduce → Test → Fix → Commit	Bug fixes

Available Agents

Agent	Purpose
feature-planner	Define feature specs with acceptance criteria
tdd-test-writer	Write failing tests (RED phase)
implementation-agent	Write code to pass tests (GREEN phase)
review-agent	Verify correctness, investigate bugs
refactor-agent	Improve code quality (REFACTOR phase)
coverage-hardener	Add test coverage to existing code

Note

This workflow is personally tested and constantly evolving. There may be better practices and tools — contributions and feedback welcome.