chore: migrate CLAUDE.md to @-import rule structure (custodian integration)
Register with state-hub under custodian domain. Replace monolithic CLAUDE.md with thin @-import index; distribute content into .claude/rules/ per ops-bridge pattern. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
26
.claude/rules/architecture.md
Normal file
26
.claude/rules/architecture.md
Normal file
@@ -0,0 +1,26 @@
|
|||||||
|
## Architecture
|
||||||
|
|
||||||
|
kaizen-agentic has two distinct layers:
|
||||||
|
|
||||||
|
### 1. Python framework (`src/kaizen_agentic/`)
|
||||||
|
|
||||||
|
- **`core.py`** — `Agent` (abstract base) + `AgentConfig` (dataclass). Tracks performance, supports config updates, implements kaizen interface.
|
||||||
|
- **`optimization.py`** — `OptimizationLoop` (runs improvement cycles, detects trends, generates recommendations) + `PerformanceMetrics` (execution time, success rate, quality scores).
|
||||||
|
|
||||||
|
### 2. Agent definitions (`agents/` — 17 files)
|
||||||
|
|
||||||
|
Markdown instruction sets read and followed by Claude. Not executables. Naming convention: `agent-{name}.md`.
|
||||||
|
|
||||||
|
| Category | Agents |
|
||||||
|
|----------|--------|
|
||||||
|
| Testing | `tdd-workflow`, `test-maintenance`, `testing-efficiency` |
|
||||||
|
| Quality | `code-refactoring`, `datamodel-optimization`, `optimization` |
|
||||||
|
| Process | `requirements-engineering`, `keepaTodofile`, `keepaChangelog`, `keepaContributingfile`, `project-management`, `priority-evaluation` |
|
||||||
|
| Infrastructure | `setupRepository`, `tooling-optimization` |
|
||||||
|
| Release | `releaseManager` |
|
||||||
|
| Docs | `claude-documentation` |
|
||||||
|
| Support | `wisdom-encouragement` |
|
||||||
|
|
||||||
|
### Custodian integration
|
||||||
|
|
||||||
|
The state-hub MCP resolves the agents directory via `host_paths[hostname]` → `local_path`. Tools: `list_kaizen_agents(category?)`, `get_kaizen_agent(name)`.
|
||||||
38
.claude/rules/first-session.md
Normal file
38
.claude/rules/first-session.md
Normal file
@@ -0,0 +1,38 @@
|
|||||||
|
## First Session Protocol
|
||||||
|
|
||||||
|
Triggered when `get_domain_summary("custodian")` shows **no workstreams**.
|
||||||
|
The project is registered but work has not yet been structured.
|
||||||
|
|
||||||
|
**Step 1 — Read, don't write**
|
||||||
|
- `~/the-custodian/canon/projects/custodian/project_charter_v0.1.md` — purpose, scope
|
||||||
|
- `~/the-custodian/canon/projects/custodian/roadmap_v0.1.md` — planned phases
|
||||||
|
- Scan repo root: README, directory structure, existing code or docs
|
||||||
|
|
||||||
|
**Step 2 — Survey in-progress work**
|
||||||
|
Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
|
||||||
|
|
||||||
|
**Step 3 — Propose workstreams to Bernd**
|
||||||
|
Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
|
||||||
|
roadmap phase. **Wait for approval before creating.**
|
||||||
|
|
||||||
|
**Step 4 — Create workplan file first, then DB record (ADR-001)**
|
||||||
|
```
|
||||||
|
workplans/kaizen-agentic-WP-NNNN-<slug>.md ← write this first
|
||||||
|
```
|
||||||
|
Then register in the hub:
|
||||||
|
```
|
||||||
|
create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...")
|
||||||
|
create_task(workstream_id="<id>", title="...", priority="high|medium|low")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 5 — Record the setup**
|
||||||
|
```
|
||||||
|
add_progress_event(
|
||||||
|
summary="First session: structured custodian into N workstreams, M tasks",
|
||||||
|
event_type="milestone",
|
||||||
|
topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
|
||||||
|
detail={"workstreams": [...], "tasks_created": M}
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
<!-- Delete or archive this file once past first session -->
|
||||||
8
.claude/rules/repo-boundary.md
Normal file
8
.claude/rules/repo-boundary.md
Normal file
@@ -0,0 +1,8 @@
|
|||||||
|
## Repo boundary
|
||||||
|
|
||||||
|
This repo owns **kaizen-agentic** only. It does not own:
|
||||||
|
|
||||||
|
- State-hub MCP integration code → `the-custodian/state-hub/mcp_server/server.py`
|
||||||
|
- Agent discovery tools (`list_kaizen_agents`, `get_kaizen_agent`) → `the-custodian`
|
||||||
|
- Custodian coordination and workplan tracking → `the-custodian`
|
||||||
|
- Deployment to custodiancore → `ops-bridge`
|
||||||
9
.claude/rules/repo-identity.md
Normal file
9
.claude/rules/repo-identity.md
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
## Repo Identity
|
||||||
|
|
||||||
|
**Purpose:** kaizen-agentic — AI agent development framework embracing kaizen (continuous improvement). Provides 17 specialized Claude Code companion agents plus an OptimizationLoop framework for continuous performance measurement and refinement.
|
||||||
|
|
||||||
|
**Domain:** custodian
|
||||||
|
**Repo slug:** kaizen-agentic
|
||||||
|
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
|
||||||
|
|
||||||
|
**Custodian integration:** This repo is the single source of truth for all kaizen agents. The state-hub MCP exposes `list_kaizen_agents()` and `get_kaizen_agent(name)` tools so any connected session can discover and load agents without a local copy.
|
||||||
48
.claude/rules/session-protocol.md
Normal file
48
.claude/rules/session-protocol.md
Normal file
@@ -0,0 +1,48 @@
|
|||||||
|
## Session Protocol
|
||||||
|
|
||||||
|
State Hub: http://127.0.0.1:8000
|
||||||
|
|
||||||
|
**Step 1 — Orient**
|
||||||
|
```
|
||||||
|
get_domain_summary("custodian")
|
||||||
|
```
|
||||||
|
If offline: `cd ~/the-custodian/state-hub && make api`
|
||||||
|
|
||||||
|
**Step 2 — Check inbox**
|
||||||
|
```
|
||||||
|
get_messages(to_agent="kaizen-agentic", unread_only=True)
|
||||||
|
```
|
||||||
|
Mark read with `mark_message_read(message_id)`. Reply or act on coordination
|
||||||
|
requests before proceeding.
|
||||||
|
|
||||||
|
**Step 3 — Scan workplans**
|
||||||
|
```bash
|
||||||
|
ls workplans/
|
||||||
|
```
|
||||||
|
For each file with `status: active`, note pending `todo`/`in_progress` tasks.
|
||||||
|
|
||||||
|
**Step 4 — Present brief**
|
||||||
|
|
||||||
|
1. **Active workstreams** for `custodian` — title, task counts, blocking decisions
|
||||||
|
2. **Pending tasks** from `workplans/` + any `[repo:kaizen-agentic]` hub tasks
|
||||||
|
3. **Goal guidance** — if `goal_guidance` in summary:
|
||||||
|
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
|
||||||
|
- `alignment_warnings`: flag if active work is not aligned with current goal
|
||||||
|
4. **Suggested next action** — highest-priority open item
|
||||||
|
5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
|
||||||
|
|
||||||
|
If no workstreams: follow First Session Protocol (`first-session.md`).
|
||||||
|
|
||||||
|
**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
|
||||||
|
|
||||||
|
> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
|
||||||
|
> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
|
||||||
|
|
||||||
|
**Session close:**
|
||||||
|
```
|
||||||
|
add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="<uuid>")
|
||||||
|
```
|
||||||
|
If workplan files were modified:
|
||||||
|
```bash
|
||||||
|
cd ~/the-custodian/state-hub && make fix-consistency REPO=kaizen-agentic
|
||||||
|
```
|
||||||
43
.claude/rules/stack-and-commands.md
Normal file
43
.claude/rules/stack-and-commands.md
Normal file
@@ -0,0 +1,43 @@
|
|||||||
|
## Stack and Commands
|
||||||
|
|
||||||
|
**Language:** Python 3.8+
|
||||||
|
**Package manager:** uv / pip (`.venv/`)
|
||||||
|
**Test runner:** pytest
|
||||||
|
**Linter/formatter:** flake8 (100-char), black (88-char), mypy (strict)
|
||||||
|
|
||||||
|
### Essential commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make setup-complete # First-time setup: venv + package + dev deps
|
||||||
|
source .venv/bin/activate
|
||||||
|
make test # Run full test suite
|
||||||
|
make lint # flake8 linting
|
||||||
|
make format # black formatting
|
||||||
|
make clean # Remove build artifacts
|
||||||
|
```
|
||||||
|
|
||||||
|
### TDD workflow
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make tdd-start ISSUE=X # Start issue with requirements validation
|
||||||
|
make tdd-add-test # Add test to current workspace
|
||||||
|
make tdd-status # Show workspace state
|
||||||
|
make tdd-finish # Move tests to main suite
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make issue-list # All issues (Gitea)
|
||||||
|
make issue-list-open # Open backlog
|
||||||
|
make issue-show ISSUE=X # Issue detail
|
||||||
|
make issue-create TITLE='...' BODY='...'
|
||||||
|
```
|
||||||
|
|
||||||
|
Run `make help` to see all available targets.
|
||||||
|
|
||||||
|
### Core dependencies (pyproject.toml)
|
||||||
|
|
||||||
|
- `pyyaml>=6.0` — YAML config
|
||||||
|
- `click>=8.0.0` — CLI framework
|
||||||
|
- `pydantic>=2.0.0` — Data validation
|
||||||
12
.claude/rules/workplan-convention.md
Normal file
12
.claude/rules/workplan-convention.md
Normal file
@@ -0,0 +1,12 @@
|
|||||||
|
## Workplan Convention (ADR-001)
|
||||||
|
|
||||||
|
File location: `workplans/kaizen-agentic-WP-NNNN-<slug>.md`
|
||||||
|
ID prefix: `KAIZEN-WP`
|
||||||
|
|
||||||
|
Work items originate as files in this repo **before** being registered in the hub.
|
||||||
|
|
||||||
|
Ecosystem todos from other agents arrive as `[repo:kaizen-agentic]` hub tasks —
|
||||||
|
visible at session start. Pick one up by creating the workplan file, then registering
|
||||||
|
the workstream.
|
||||||
|
|
||||||
|
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
|
||||||
379
CLAUDE.md
379
CLAUDE.md
@@ -1,370 +1,9 @@
|
|||||||
# CLAUDE.md
|
# kaizen-agentic — Claude Code Instructions
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
@.claude/rules/repo-identity.md
|
||||||
|
@.claude/rules/session-protocol.md
|
||||||
## Project Overview
|
@.claude/rules/first-session.md
|
||||||
|
@.claude/rules/workplan-convention.md
|
||||||
Kaizen Agentic is an AI agent development framework that embraces the Japanese concept of "kaizen" (continuous improvement). Every coding subagent becomes part of an optimization loop where performance is measured, patterns are analyzed, and specifications are refined over time.
|
@.claude/rules/stack-and-commands.md
|
||||||
|
@.claude/rules/architecture.md
|
||||||
## Repository Structure
|
@.claude/rules/repo-boundary.md
|
||||||
|
|
||||||
This is a modern Python project with agent development focus:
|
|
||||||
|
|
||||||
```
|
|
||||||
kaizen-agentic/
|
|
||||||
├── Makefile # Comprehensive development commands and workflows
|
|
||||||
├── pyproject.toml # Python project configuration and dependencies
|
|
||||||
├── src/kaizen_agentic/ # Main Python package
|
|
||||||
│ ├── __init__.py # Package exports and version info
|
|
||||||
│ ├── core.py # Core Agent and AgentConfig classes
|
|
||||||
│ └── optimization.py # OptimizationLoop and PerformanceMetrics
|
|
||||||
├── tests/ # Test suite with pytest
|
|
||||||
│ ├── __init__.py
|
|
||||||
│ └── test_core.py # Core functionality tests
|
|
||||||
├── agents/ # Agent definitions and configurations (17 total)
|
|
||||||
│ ├── agent-claude-documentation.md
|
|
||||||
│ ├── agent-code-refactoring.md
|
|
||||||
│ ├── agent-datamodel-optimization.md
|
|
||||||
│ ├── agent-keepaChangelog.md
|
|
||||||
│ ├── agent-keepaContributingfile.md
|
|
||||||
│ ├── agent-keepaTodofile.md
|
|
||||||
│ ├── agent-optimization.md
|
|
||||||
│ ├── agent-priority-evaluation.md
|
|
||||||
│ ├── agent-project-management.md
|
|
||||||
│ ├── agent-releaseManager.md
|
|
||||||
│ ├── agent-requirements-engineering.md
|
|
||||||
│ ├── agent-setupRepository.md
|
|
||||||
│ ├── agent-tdd-workflow.md
|
|
||||||
│ ├── agent-test-maintenance.md
|
|
||||||
│ ├── agent-testing-efficiency.md
|
|
||||||
│ ├── agent-tooling-optimization.md
|
|
||||||
│ └── agent-wisdom-encouragement.md
|
|
||||||
├── .claude/ # Claude Code configuration
|
|
||||||
│ └── settings.local.json # Local permissions and settings
|
|
||||||
├── .venv/ # Python virtual environment (created by setup)
|
|
||||||
├── TODO.md # Current todofile (Keep a Todofile format)
|
|
||||||
├── CHANGELOG.md # Version history (Keep a Changelog format)
|
|
||||||
├── CONTRIBUTING.md # Developer contribution guidelines
|
|
||||||
├── CLAUDE.md # Claude Code guidance documentation
|
|
||||||
├── LICENSE # MIT License
|
|
||||||
└── README.md # Project overview
|
|
||||||
```
|
|
||||||
|
|
||||||
## Quick Start
|
|
||||||
|
|
||||||
For first-time setup or when starting fresh:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Complete setup with development dependencies
|
|
||||||
make setup-complete
|
|
||||||
|
|
||||||
# Activate virtual environment
|
|
||||||
source .venv/bin/activate
|
|
||||||
|
|
||||||
# Verify everything works
|
|
||||||
make test && make lint
|
|
||||||
```
|
|
||||||
|
|
||||||
## Key Development Commands
|
|
||||||
|
|
||||||
The Makefile provides an extensive set of commands for development workflow. Use `make help` to see all available commands.
|
|
||||||
|
|
||||||
### Essential Commands
|
|
||||||
|
|
||||||
- `make help` - Show all available commands with descriptions
|
|
||||||
- `make setup` - Basic project setup (creates venv + installs package)
|
|
||||||
- `make setup-complete` - Complete setup including dev dependencies (recommended)
|
|
||||||
- `make test` - Run all tests with pytest
|
|
||||||
- `make lint` - Run code linting with flake8 (100 char line length)
|
|
||||||
- `make format` - Format code with black
|
|
||||||
- `make clean` - Clean build artifacts and cache
|
|
||||||
|
|
||||||
### Environment Management
|
|
||||||
|
|
||||||
- `make venv-status` - Check virtual environment status
|
|
||||||
- `make ensure-project-structure` - Auto-create Python project structure if missing
|
|
||||||
- `make install-dev` - Install package in development mode
|
|
||||||
- `make setup-dev` - Install development dependencies (pytest, black, flake8, mypy)
|
|
||||||
- `make install-deps` - Install dependencies user-local (fallback option)
|
|
||||||
- `make install-system` - Install system dependencies via apt (requires sudo)
|
|
||||||
|
|
||||||
### Testing Infrastructure
|
|
||||||
|
|
||||||
The project includes comprehensive testing capabilities:
|
|
||||||
|
|
||||||
#### Basic Testing
|
|
||||||
- `make test` - Run all tests with pytest
|
|
||||||
- `make test-status` - Show test status summary without re-running
|
|
||||||
- `make test-new` - Create new test file template
|
|
||||||
- `make test-coverage ISSUE=X` - Analyze test coverage for specific issue
|
|
||||||
|
|
||||||
#### Advanced Testing
|
|
||||||
- `make test-clean` - Clean test run (exclude workspaces, fresh cache)
|
|
||||||
- `make test-tdd` - Quick TDD tests for fast feedback (<30s)
|
|
||||||
- `make test-changed` - Run tests for changed files only
|
|
||||||
- `make test-module MODULE=name` - Run tests for specific module
|
|
||||||
- `make test-efficient` - Enhanced test suite excluding workspaces
|
|
||||||
|
|
||||||
#### Architectural Testing
|
|
||||||
- `make test-arch` - Run tests in architectural order (reverse dependency)
|
|
||||||
- `make test-foundation` - Foundation layer tests (fastest feedback)
|
|
||||||
- `make test-infrastructure` - Infrastructure layer tests
|
|
||||||
- `make test-domain` - Domain layer tests (business logic)
|
|
||||||
- `make test-quick` - Foundation + infrastructure only (fast)
|
|
||||||
|
|
||||||
#### Randomized Testing
|
|
||||||
- `make test-random` - Run tests in random order to detect hidden dependencies
|
|
||||||
- `make test-random-seed SEED=X` - Run with specific seed for reproducibility
|
|
||||||
- `make test-random-repeat NUM=X` - Run multiple random iterations
|
|
||||||
|
|
||||||
### Issue Management
|
|
||||||
|
|
||||||
The project uses Gitea for issue tracking with integrated CLI tools:
|
|
||||||
|
|
||||||
- `make issue-list` - Show all issues with status and priority
|
|
||||||
- `make issue-list-open` - Show only open issues (active backlog)
|
|
||||||
- `make issue-show ISSUE=X` - Show detailed view of specific issue
|
|
||||||
- `make issue-create TITLE='...' BODY='...'` - Create new issue
|
|
||||||
- `make issue-close ISSUE=X` - Close an issue
|
|
||||||
- `make issue-get` - Export issues to various formats (CSV, JSON, TSV)
|
|
||||||
|
|
||||||
### TDD Workflow
|
|
||||||
|
|
||||||
Complete test-driven development support:
|
|
||||||
|
|
||||||
- `make tdd-start ISSUE=X` - Start working on issue with requirements validation
|
|
||||||
- `make tdd-add-test` - Add test to current issue workspace
|
|
||||||
- `make tdd-status` - Show current workspace state
|
|
||||||
- `make tdd-finish` - Complete issue work (move tests to main)
|
|
||||||
- `make test-from-issue ISSUE=X` - Generate test skeleton from issue
|
|
||||||
|
|
||||||
## Core Framework Architecture
|
|
||||||
|
|
||||||
The repository provides a working AI agent framework with kaizen optimization:
|
|
||||||
|
|
||||||
### Core Classes
|
|
||||||
|
|
||||||
1. **AgentConfig** (`src/kaizen_agentic/core.py`)
|
|
||||||
- Configuration dataclass for agents
|
|
||||||
- Includes name, description, model, instructions, and metadata
|
|
||||||
|
|
||||||
2. **Agent** (`src/kaizen_agentic/core.py`)
|
|
||||||
- Abstract base class for AI agents
|
|
||||||
- Provides performance tracking and configuration updates
|
|
||||||
- Implements kaizen optimization interface
|
|
||||||
|
|
||||||
3. **OptimizationLoop** (`src/kaizen_agentic/optimization.py`)
|
|
||||||
- Implements continuous improvement cycles
|
|
||||||
- Performance analysis and trend detection
|
|
||||||
- Generates improvement recommendations
|
|
||||||
|
|
||||||
4. **PerformanceMetrics** (`src/kaizen_agentic/optimization.py`)
|
|
||||||
- Container for agent performance data
|
|
||||||
- Tracks execution time, success rate, quality scores
|
|
||||||
|
|
||||||
### Agent System Architecture
|
|
||||||
|
|
||||||
Specialized agent definitions in `agents/` directory (17 total):
|
|
||||||
|
|
||||||
#### Documentation & Claude Integration
|
|
||||||
1. **claude-documentation** (`agent-claude-documentation.md`)
|
|
||||||
- Specialized assistant for Claude and Claude Code documentation, features, and best practices
|
|
||||||
- Access to official docs.claude.com resources and Claude Code configuration
|
|
||||||
|
|
||||||
#### Project Management
|
|
||||||
2. **project-management** (`agent-project-management.md`)
|
|
||||||
- Specialized assistant for project status, progress tracking, and development planning
|
|
||||||
- Manages project coordination and workflow optimization
|
|
||||||
|
|
||||||
3. **priority-evaluation** (`agent-priority-evaluation.md`)
|
|
||||||
- Specialized assistant to help evaluate and establish priorities for issues and tasks
|
|
||||||
- Decision support and task prioritization
|
|
||||||
|
|
||||||
4. **releaseManager** (`agent-releaseManager.md`)
|
|
||||||
- Manages software releases, version control, and publication workflows for Python packages
|
|
||||||
- Handles semantic versioning and release automation
|
|
||||||
|
|
||||||
#### Documentation Keepers
|
|
||||||
5. **keepaTodofile** (`agent-keepaTodofile.md`)
|
|
||||||
- Specialized assistant for maintaining TODO.md files following Keep a Todofile V0.0.1 format
|
|
||||||
- Task tracking, progress monitoring, and workflow optimization
|
|
||||||
|
|
||||||
6. **keepaChangelog** (`agent-keepaChangelog.md`)
|
|
||||||
- Specialized assistant for maintaining CHANGELOG.md files following Keep a Changelog format
|
|
||||||
- Semantic versioning and change categorization
|
|
||||||
|
|
||||||
7. **keepaContributingfile** (`agent-keepaContributingfile.md`)
|
|
||||||
- Specialized assistant for maintaining CONTRIBUTING.md files following Keep a Contributing-File V0.0.1 format
|
|
||||||
- Developer onboarding and contribution guidelines
|
|
||||||
|
|
||||||
#### Development Process
|
|
||||||
8. **tdd-workflow** (`agent-tdd-workflow.md`)
|
|
||||||
- Expert guidance for the TDD8 workflow methodology
|
|
||||||
- ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management
|
|
||||||
|
|
||||||
9. **requirements-engineering** (`agent-requirements-engineering.md`)
|
|
||||||
- Specialized agent designed to prevent interface compatibility issues and mock object mismatches
|
|
||||||
- Ensures solid foundation planning before implementation
|
|
||||||
|
|
||||||
#### Testing & Quality Assurance
|
|
||||||
10. **test-maintenance** (`agent-test-maintenance.md`)
|
|
||||||
- Specialized agent for analyzing and fixing failing tests in the project
|
|
||||||
- Test suite maintenance and optimization
|
|
||||||
|
|
||||||
11. **testing-efficiency** (`agent-testing-efficiency.md`)
|
|
||||||
- Specialized agent designed to optimize TDD8 workflow test execution
|
|
||||||
- Resolves pytest reliability issues and enhances testing efficiency
|
|
||||||
|
|
||||||
#### Code Quality & Optimization
|
|
||||||
12. **code-refactoring** (`agent-code-refactoring.md`)
|
|
||||||
- Analyze code structure and quality, identify improvement opportunities
|
|
||||||
- Provides actionable refactoring guidance (Use PROACTIVELY)
|
|
||||||
|
|
||||||
13. **datamodel-optimization** (`agent-datamodel-optimization.md`)
|
|
||||||
- Systematically analyzes, optimizes, and enhances dataclasses, models, and data structures
|
|
||||||
- Provides comprehensive datamodel improvements
|
|
||||||
|
|
||||||
14. **optimization** (`agent-optimization.md`)
|
|
||||||
- Meta-agent that analyzes and optimizes other Claude Code subagents
|
|
||||||
- Based on performance data, usage patterns, and effectiveness metrics (Use PROACTIVELY)
|
|
||||||
|
|
||||||
#### Infrastructure & Tooling
|
|
||||||
15. **setupRepository** (`agent-setupRepository.md`)
|
|
||||||
- Specialized assistant for setting up new Python repositories following PythonVibes best practices
|
|
||||||
- Repository initialization and standards compliance
|
|
||||||
|
|
||||||
16. **tooling-optimization** (`agent-tooling-optimization.md`)
|
|
||||||
- Meta-agent that analyzes and optimizes repository tooling usage to improve development efficiency
|
|
||||||
- Discovers and recommends better tool utilization
|
|
||||||
|
|
||||||
#### Support & Guidance
|
|
||||||
17. **wisdom-encouragement** (`agent-wisdom-encouragement.md`)
|
|
||||||
- Provides encouraging wisdom and guidance for complex implementation tasks and challenging technical work
|
|
||||||
- Fortune cookie-style wisdom for developers facing technical challenges
|
|
||||||
|
|
||||||
## Development Workflow Patterns
|
|
||||||
|
|
||||||
### Kaizen Philosophy
|
|
||||||
|
|
||||||
- **Continuous Improvement**: Every coding session should measure performance and refine specifications
|
|
||||||
- **Pattern Recognition**: Analyze agent behavior and optimize workflows over time
|
|
||||||
- **Specification Evolution**: Agent definitions should be updated based on performance data
|
|
||||||
|
|
||||||
### Agent Optimization Loop
|
|
||||||
|
|
||||||
1. **Measure**: Track agent performance and effectiveness using PerformanceMetrics
|
|
||||||
2. **Analyze**: Use OptimizationLoop to identify patterns and trends
|
|
||||||
3. **Refine**: Update agent specifications and workflows based on insights
|
|
||||||
4. **Iterate**: Repeat the cycle for continuous improvement
|
|
||||||
|
|
||||||
### Development Best Practices
|
|
||||||
|
|
||||||
1. **Always use virtual environment**: Run `make venv-status` before starting
|
|
||||||
2. **Test-driven development**: Write tests first, then implementation
|
|
||||||
3. **Code quality**: Run `make lint` and `make format` before commits
|
|
||||||
4. **Performance tracking**: Use the optimization framework for agent improvements
|
|
||||||
5. **Todo tracking**: Maintain a todofile for task management and progress tracking
|
|
||||||
6. **Change documentation**: Keep a changelog for version history and feature tracking
|
|
||||||
|
|
||||||
## Python Project Configuration
|
|
||||||
|
|
||||||
### Dependencies
|
|
||||||
|
|
||||||
**Core Dependencies** (pyproject.toml):
|
|
||||||
- `pyyaml>=6.0` - YAML configuration parsing
|
|
||||||
- `click>=8.0.0` - CLI framework
|
|
||||||
- `pydantic>=2.0.0` - Data validation and settings
|
|
||||||
|
|
||||||
**Development Dependencies**:
|
|
||||||
- `pytest>=6.0.0` - Testing framework
|
|
||||||
- `black>=22.0.0` - Code formatting
|
|
||||||
- `flake8>=5.0.0` - Code linting
|
|
||||||
- `mypy>=1.0.0` - Type checking
|
|
||||||
|
|
||||||
### Code Quality Configuration
|
|
||||||
|
|
||||||
- **Black**: Line length 88, Python 3.8+ target
|
|
||||||
- **Flake8**: Max line length 100, ignores E203, W503
|
|
||||||
- **Pytest**: Configured with markers for slow, integration, e2e, smoke tests
|
|
||||||
- **MyPy**: Strict typing with comprehensive checks enabled
|
|
||||||
|
|
||||||
## Setup and Installation
|
|
||||||
|
|
||||||
### First Time Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Complete setup (recommended)
|
|
||||||
make setup-complete
|
|
||||||
|
|
||||||
# Activate environment
|
|
||||||
source .venv/bin/activate
|
|
||||||
|
|
||||||
# Verify installation
|
|
||||||
make test
|
|
||||||
```
|
|
||||||
|
|
||||||
### Alternative Setup Methods
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Basic setup only
|
|
||||||
make setup
|
|
||||||
|
|
||||||
# Manual dev dependencies
|
|
||||||
make setup-dev
|
|
||||||
|
|
||||||
# Check environment status
|
|
||||||
make venv-status
|
|
||||||
```
|
|
||||||
|
|
||||||
### Troubleshooting
|
|
||||||
|
|
||||||
If setup fails:
|
|
||||||
1. Try `make install-system` for system packages
|
|
||||||
2. Use `make install-deps-force` to override restrictions
|
|
||||||
3. Try `make install-deps-venv` for isolated environment
|
|
||||||
|
|
||||||
## Project Management Tools
|
|
||||||
|
|
||||||
### Todo Tracking
|
|
||||||
- **Purpose**: Maintain visibility into current tasks and progress
|
|
||||||
- **File**: `TODO.md` - Structured todofile following Keep a Todofile format
|
|
||||||
- **Agent**: Use `todo-keeper` agent for maintaining todofiles
|
|
||||||
- **Usage**: Track work items organized by impact type (Add, Refactor, Fix, Deprecate, Secure, Remove)
|
|
||||||
- **Benefits**: Helps maintain focus and provides clear progress indicators aligned with changelog categories
|
|
||||||
- **Integration**: Works well with issue management, TDD workflows, and changelog management
|
|
||||||
- **Structure**: Organized by change impact type, mirroring changelog categories
|
|
||||||
- **Format**: Uses markdown checkboxes within sprint-focused sections
|
|
||||||
|
|
||||||
### Changelog Management
|
|
||||||
- **Purpose**: Document changes, features, and version history
|
|
||||||
- **File**: `CHANGELOG.md` - Structured markdown file following Keep a Changelog format
|
|
||||||
- **Agent**: Use `changelog-keeper` agent for maintaining CHANGELOG.md files
|
|
||||||
- **Usage**: Track what has been added, changed, fixed, removed, deprecated, or security-related
|
|
||||||
- **Benefits**: Provides clear communication about project evolution and version impacts
|
|
||||||
- **Format**: Follows Keep a Changelog standard with semantic versioning
|
|
||||||
- **Structure**: Organized by version with categories (Added, Changed, Fixed, Deprecated, Removed, Security)
|
|
||||||
- **Integration**: Links with git tags, releases, and issue references
|
|
||||||
|
|
||||||
## Important Notes
|
|
||||||
|
|
||||||
- **Self-healing setup**: `make setup` automatically creates missing project structure
|
|
||||||
- **Comprehensive help**: Use `make help` to explore all available commands
|
|
||||||
- **Agent-focused**: Agent definitions in `agents/` directory are the core of this system
|
|
||||||
- **Quality-first**: Always run tests and linting before commits
|
|
||||||
- **TDD emphasis**: The project emphasizes test-driven development workflows
|
|
||||||
- **Kaizen approach**: Apply continuous improvement principles to all development
|
|
||||||
- **Documentation practices**: Maintain todofiles and changelogs for better project management
|
|
||||||
|
|
||||||
## Agent Usage Guidelines
|
|
||||||
|
|
||||||
When working with this repository:
|
|
||||||
|
|
||||||
1. **Read Agent Definitions**: Understand the specialized agents available in `agents/`
|
|
||||||
2. **Follow TDD Patterns**: Use the established test-driven development workflows
|
|
||||||
3. **Measure and Improve**: Apply kaizen principles using the optimization framework
|
|
||||||
4. **Update Documentation**: Keep agent definitions current with actual usage patterns
|
|
||||||
5. **Use the Framework**: Leverage the core Agent and OptimizationLoop classes for new agents
|
|
||||||
6. **Test Everything**: Use the comprehensive testing infrastructure for quality assurance
|
|
||||||
7. **Track Progress**: Maintain todofiles for current work and use changelog for completed work
|
|
||||||
8. **Document Changes**: Update changelog when adding features, fixing bugs, or making improvements
|
|
||||||
9. **Version Management**: Use changelog-keeper agent to maintain proper version history and semantic versioning
|
|
||||||
|
|||||||
Reference in New Issue
Block a user