@dtt_siye/atool 1.1.0

package/skills/ai-project-architecture/SKILL.md

@@ -0,0 +1,632 @@
+---
+name: ai-project-architecture
+description: Ensure Python AI projects comply with LangGraph 1.0+ architecture standards. Use when creating new AI projects, reviewing structure compliance, or refactoring existing projects to match PROJECT_STRUCTURE.md requirements.
+version: 1.0.0
+allowed-tools: Read, Write, Edit, Bash, Skill, Task
+---
+
+# AI Project Architecture Compliance & Refactoring
+
+Guide for ensuring Python-based AI projects comply with LangGraph 1.0+ architecture standards defined in `PROJECT_STRUCTURE.md`.
+
+## Purpose
+
+This skill ensures AI projects follow a standardized, scalable architecture that:
+- **Enforces LangGraph 1.0+ best practices** for agent-based systems
+- **Maintains consistency** across all AI projects in the codebase
+- **Enables safe refactoring** of existing projects to standard structure
+- **Prevents architectural drift** through compliance checking
+- **Integrates quality skills** (software-architecture, test-driven-development, systematic-debugging)
+
+**Core principle**: All AI projects must follow the architecture defined in `PROJECT_STRUCTURE.md`. Deviations require explicit documentation and approval.
+
+**Violating the letter of these iron laws is violating the spirit of this skill.**
+
+## When This Skill Activates
+
+This skill activates when:
+- Creating a new AI project (FastAPI + LangGraph 1.0+ based)
+- Reviewing an existing AI project's structure compliance
+- Refactoring an AI project to match standard architecture
+- Explicitly invoked via "check architecture compliance", "review project structure", "refactor to standard"
+- Detecting Python AI project patterns (agents/, LangGraph, FastAPI)
+
+## The Iron Laws
+
+```
+IRON LAW 1: NO FABRICATION
+Never assume or make up code behavior. Work only with existing, verified code.
+```
+
+```
+IRON LAW 2: NO NEW FEATURES DURING REFACTORING
+Refactoring = structural change ONLY. Any behavioral change is a violation.
+```
+
+```
+IRON LAW 3: INCREMENTAL EXECUTION
+Break refactoring into single-agent batches. Self-review after each batch.
+```
+
+```
+IRON LAW 4: MANDATORY QUALITY GATES
+systematic-debugging review is MANDATORY after each code completion phase.
+```
+
+```
+IRON LAW 5: SKILL INTEGRATION
+This skill CANNOT operate independently. MUST call required skills at specified points.
+```
+
+**No exceptions without explicit user override.**
+
+## Critical Dependencies
+
+This skill **depends on** and **must invoke** these skills:
+
+### software-architecture
+**When to call:**
+- During architectural decisions (module placement, separation of concerns)
+- When naming modules, services, agents (avoid utils/helpers)
+- When validating structure against Clean Architecture/DDD principles
+- When checking for architectural anti-patterns
+
+**What to pass:** Current code context, architectural decision being made
+
+**Expected output:** Validation against Clean Architecture principles, domain-specific naming guidance
+
+### test-driven-development
+**When to call:**
+- Before writing ANY new code (Red-Green-Refactor)
+- Before refactoring migrated code
+- When writing tests for migrated code
+
+**What to pass:** Feature requirements, code being tested
+
+**Expected output:** Failing tests first, then minimal implementation to pass
+
+### systematic-debugging
+**When to call:**
+- **MANDATORY** after Phase 3 (Structure Migration)
+- **MANDATORY** after Phase 4 (Code Verification)
+- **MANDATORY** after Phase 5 (Archive & Test)
+- When encountering issues during migration
+
+**What to pass:** Code changes made, test results, any issues encountered
+
+**Expected output:** Root cause analysis, validation that changes are correct
+
+## Five-Phase Workflow
+
+### Phase 1: Compliance Assessment
+
+**Objective**: Analyze current project structure against `PROJECT_STRUCTURE.md` requirements.
+
+**Activities**:
+
+1. **Classify each component by requirement tier**
+   - **Tier 1 (Mandatory Required)**: Required in ALL projects
+     - Top-level: `agents/`, `apps/`, `core/`, `configs/`
+     - Per-agent: `nodes/`, `services/`, `models/api.py`, `tools/`
+     - **Severity if missing**: CRITICAL
+   - **Tier 2 (Conditionally Required)**: Required IF specific conditions met
+     - `models/` root (only if shared ORM models across agents)
+     - Agent's `models/orm.py` (only if agent has independent DB tables)
+     - Agent's `models/state.py` (only if agent uses custom LangGraph state)
+     - Agent's `graph.py` (only if agent uses LangGraph)
+     - Agent's `checkpoint.py` (only if agent uses state persistence)
+     - Agent's `views.py` (only if agent exposes HTTP endpoints)
+     - Agent's `constants.py` (optional - only if agent has constants)
+     - **Severity if missing**: HIGH (when condition applies)
+   - **Tier 3 (Fully Optional)**: Recommended but not required
+     - `tests/`, `bin/`, `docs/`, `logs/`, `temp/`
+     - **Severity if missing**: LOW (informational only)
+
+2. **Detect conditions for Tier 2 components**
+   - Check if project has database operations → `models/` root needed
+   - Check if agent imports StateGraph → `graph.py` needed
+   - Check if agent uses @router or APIRouter → `views.py` needed
+   - Check if agent uses checkpoint/checkpointer → `checkpoint.py` needed
+   - Check if agent has ORM models → `models/orm.py` needed
+   - Check if agent uses TypedDict or custom state → `models/state.py` needed
+   - Document WHY each Tier 2 component is (or isn't) required
+
+3. **Scan directory structure**
+   - Check for Tier 1 directories (agents/, apps/, core/, configs/)
+   - Check for Tier 2 directories (if conditions met)
+   - Check for Tier 3 directories (optional but recommended)
+
+4. **Verify agent structure**
+   - For each agent in `agents/{agent_name}/`:
+     - Tier 1 (Mandatory): `nodes/`, `services/`, `models/api.py`, `tools/`
+     - Tier 2 (Conditional): `graph.py`, `checkpoint.py`, `views.py`, `models/orm.py`, `models/state.py`
+     - Tier 3 (Optional): `constants.py`
+
+5. **Check configuration structure**
+   - `configs/app_config.py` (main config)
+   - `configs/base/` (logger, security)
+   - `configs/deploy/` (build, runtime, Docker files)
+   - `configs/integrations/` (database, redis, llm, etc.)
+
+6. **Identify compliance gaps**
+   - Missing Tier 1 components (CRITICAL)
+   - Missing Tier 2 components when conditions apply (HIGH)
+   - Missing Tier 3 components (LOW - informational)
+   - Incorrect agent structure
+   - Naming convention violations
+   - Mixed concerns (business logic in wrong layer)
+
+7. **Generate tiered compliance report**
+   - Overall compliance score (percentage)
+   - Severity levels:
+     - **CRITICAL**: Missing Tier 1 (Mandatory) components - blocks development
+     - **HIGH**: Missing Tier 2 (Conditional) components when condition applies
+     - **MEDIUM**: Moderate issues (e.g., naming inconsistencies)
+     - **LOW**: Missing Tier 3 (Optional) components or cosmetic issues
+   - Tier classification for each component
+   - Condition detection results for Tier 2 components
+   - Recommendations with priority
+
+**Deliverables**: Compliance report (use `templates/compliance-report.md`)
+
+**Exit Criteria**:
+- [ ] All components classified by tier (Tier 1/2/3)
+- [ ] Conditions detected for Tier 2 components
+- [ ] Directory structure scanned
+- [ ] Agent structure validated
+- [ ] Compliance gaps identified with appropriate severity
+- [ ] Tiered compliance report generated and presented to user
+
+**Integration**: None (analysis phase only)
+
+---
+
+### Phase 2: Refactoring Planning
+
+**Objective**: Create detailed migration plan from current structure to standard structure.
+
+**Activities**:
+
+1. **Document current structure**
+   - Create `old_structure.md` with:
+     - Current directory tree
+     - Current agent list
+     - Current file locations
+     - Import dependency graph
+
+2. **Create migration mapping**
+   - Map each file/directory: old_path → new_path
+   - Identify shared/common components
+   - Identify agent-specific components
+   - Note any ambiguous cases
+
+3. **Sequence migration by priority**
+   - Start with: shared components (apps/, core/, models/)
+   - Then: independent agents (no dependencies on other agents)
+   - Then: dependent agents (depend on migrated agents)
+   - Last: agent-specific configurations and tools
+
+4. **Define migration batches**
+   - Each batch = independently verifiable unit
+   - Prefer: single agent per batch
+   - Large agents: split into nodes/, services/, models/, tools/ batches
+   - Each batch must have clear entry/exit criteria
+
+5. **Create rollback plan**
+   - For each batch: how to revert if migration fails
+   - Checkpoints: commit after each successful batch
+   - Validation: tests must pass before proceeding
+
+**Deliverables**: Migration plan (use `templates/migration-plan.md`)
+
+**Exit Criteria**:
+- [ ] Current structure documented
+- [ ] Migration mapping created
+- [ ] Migration sequence defined
+- [ ] Batches identified with entry/exit criteria
+- [ ] Rollback plan defined
+- [ ] **User approval obtained** (MANDATORY)
+
+**Integration**:
+- **software-architecture**: Validate migration plan against Clean Architecture principles
+
+---
+
+### Phase 3: Structure Migration
+
+**Objective**: Create new directory structure and migrate code while preserving exact functionality.
+
+**Activities**:
+
+1. **Create new directory structure**
+   - Create standard directories per `PROJECT_STRUCTURE.md`
+   - DO NOT delete old structure yet
+   - Use parallel structure: `new_agents/`, `new_apps/`, etc. (temporary)
+
+2. **Migrate shared components first**
+   - Migrate `apps/` (LLM management, utils, logs API)
+   - Migrate `core/` (exceptions, middleware, logging, etc.)
+   - Migrate `models/` (shared ORM models)
+   - Migrate `configs/` (all configuration files)
+   - Update all imports as you go
+
+3. **Migrate agents in priority order**
+   - For each agent in sequence:
+     - Create `agents/{agent_name}/` with required subdirectories
+     - Migrate `nodes/` → `agents/{agent_name}/nodes/`
+     - Migrate `services/` → `agents/{agent_name}/services/`
+     - Migrate `models/` → `agents/{agent_name}/models/`
+     - Migrate `tools/` → `agents/{agent_name}/tools/`
+     - Migrate optional files (graph.py, checkpoint.py, views.py, constants.py)
+     - Update all import statements:
+       - Old: `from old_apps.xyz import ABC`
+       - New: `from apps.xyz import ABC`
+     - Verify no broken imports
+
+4. **Update all cross-references**
+   - Update imports in all migrated files
+   - Update references in configuration files
+   - Update references in documentation
+   - Search for old paths and replace with new paths
+
+5. **Validate after each batch**
+   - Run Python syntax check: `python -m py_compile`
+   - Run existing tests (if any)
+   - Verify imports resolve: `python -c "import agents.{agent_name}"`
+
+**IRON LAW (Non-negotiable)**:
+- **NO new features**: Only structural changes, NO behavioral changes
+- **NO "improvements"**: Don't "fix" or "optimize" code during migration
+- **NO "missing" features**: Don't add features you think are missing
+- **Exact preservation**: All behavior must remain exactly the same
+
+**Deliverables**: Migrated codebase in new structure
+
+**Exit Criteria**:
+- [ ] New directory structure created
+- [ ] All shared components migrated
+- [ ] All agents migrated in priority order
+- [ ] All imports updated and verified
+- [ ] No syntax errors
+- [ ] Existing tests still pass (if any)
+
+**Integration**:
+- **software-architecture**: Validate structure, naming, and separation of concerns
+- **test-driven-development**: Write tests for migrated code (if tests don't exist)
+
+---
+
+### Phase 4: Code Verification
+
+**Objective**: Verify that migrated code is functionally equivalent to original.
+
+**Activities**:
+
+1. **Comprehensive code review**
+   - Review each migrated file
+   - Verify no behavioral changes
+   - Check for accidental modifications
+   - Validate all imports are correct
+
+2. **Verify all imports resolve**
+   - Check each import statement
+   - Verify no circular dependencies
+   - Validate relative vs absolute imports
+   - Test import chains: `python -c "from agents.x.y import z"`
+
+3. **Check all cross-references updated**
+   - Configuration files
+   - Documentation
+   - Test files
+   - Scripts and tooling
+
+4. **Validate no behavior changes**
+   - Compare functionality line-by-line
+   - Run existing tests and verify same results
+   - Manual testing of key features
+   - Performance comparison (should be identical)
+
+5. **Generate verification report**
+   - List all files reviewed
+   - List all imports verified
+   - List all references updated
+   - Note any discrepancies found (and fixed)
+
+**Deliverables**: Verification report (use `templates/verification-checklist.md`)
+
+**Exit Criteria**:
+- [ ] All migrated files reviewed
+- [ ] All imports verified and resolving
+- [ ] All references updated
+- [ ] No behavioral changes detected
+- [ ] Existing tests pass with same results
+- [ ] Verification report generated
+
+**QUALITY GATE (MANDATORY)**:
+- **Call systematic-debugging skill** for thorough review
+- Pass all validation checks
+- No unresolved issues
+
+**Integration**:
+- **systematic-debugging (MANDATORY)**: Root cause analysis, validation of migration correctness
+- **software-architecture**: Final architectural validation
+
+---
+
+### Phase 5: Archive & Test
+
+**Objective**: Archive old structure and ensure comprehensive test coverage.
+
+**Activities**:
+
+1. **Move old structure to archive**
+   - Create `archivecodes/` directory
+   - Move old structure with timestamp: `archivecodes/old_structure_YYYYMMDD/`
+   - Create README in archive explaining what was archived
+   - Commit with message: "Archive old structure before migration"
+
+2. **Rename new structure to final**
+   - Remove temporary `new_` prefixes
+   - Final structure: `agents/`, `apps/`, `core/`, `configs/`, etc.
+
+3. **Write comprehensive unit tests**
+   - Use **test-driven-development skill (MANDATORY)**
+   - For each migrated component:
+     - Write failing test first (RED)
+     - Migrate/verify code passes test (GREEN)
+     - Refactor if needed (REFACTOR)
+   - Target: 100% coverage for migrated code
+   - Test all public interfaces
+   - Test edge cases and error conditions
+
+4. **Execute full test suite**
+   - Run all tests: `pytest tests/`
+   - Verify all tests pass
+   - Generate coverage report: `pytest --cov=`
+   - Fix any failing tests
+
+5. **Documentation updates**
+   - Update architecture documentation
+   - Create migration changelog
+   - Update README with new structure
+   - Document any deviations from standard
+
+6. **Final quality review**
+   - **Call systematic-debugging skill (MANDATORY)**
+   - **Call test-driven-development skill (MANDATORY)**
+   - Review test coverage
+   - Review documentation
+   - Verify all quality gates passed
+
+**Deliverables**:
+- Archived old code in `archivecodes/`
+- Comprehensive test suite
+- Updated documentation
+- Migration changelog
+
+**Exit Criteria**:
+- [ ] Old structure moved to `archivecodes/`
+- [ ] New structure in place (no temporary prefixes)
+- [ ] Comprehensive unit tests written using TDD
+- [ ] All tests pass (100% success rate)
+- [ ] Test coverage ≥ 80% (prefer 100% for migrated code)
+- [ ] Documentation updated
+- [ ] Migration changelog created
+- [ ] Final quality reviews completed
+
+**QUALITY GATES (MANDATORY)**:
+- **systematic-debugging review**: All code changes validated
+- **test-driven-development review**: All tests follow TDD principles
+- All tests pass
+- Coverage threshold met
+
+**Integration**:
+- **test-driven-development (MANDATORY)**: Write all tests using TDD methodology
+- **systematic-debugging (MANDATORY)**: Final validation of migration
+
+---
+
+## Validation Checklists
+
+### Phase 1: Compliance Assessment Checklist
+
+- [ ] All required top-level directories present
+- [ ] All agents have required subdirectories (nodes/, services/, models/, tools/)
+- [ ] Configuration structure matches standard
+- [ ] Naming conventions followed (lowercase, kebab-case)
+- [ ] No mixed concerns (business logic in correct layer)
+- [ ] Compliance report generated with severity levels
+- [ ] Report presented to user
+
+### Phase 2: Migration Planning Checklist
+
+- [ ] Current structure documented in `old_structure.md`
+- [ ] Migration mapping created (old_path → new_path)
+- [ ] Migration sequence defined (shared → independent → dependent)
+- [ ] Migration batches identified (prefer single agent per batch)
+- [ ] Rollback plan defined for each batch
+- [ ] software-architecture skill consulted for validation
+- [ ] **User approval obtained** (MANDATORY)
+
+### Phase 3: Structure Migration Checklist
+
+- [ ] New directory structure created per standard
+- [ ] Shared components migrated first (apps/, core/, models/)
+- [ ] Agents migrated in priority order
+- [ ] All imports updated and verified
+- [ ] No syntax errors (`python -m py_compile`)
+- [ ] Existing tests still pass
+- [ ] NO new features added (Iron Law compliance)
+- [ ] NO behavioral changes (exact preservation)
+- [ ] software-architecture skill called for validation
+- [ ] test-driven-development skill called for test writing
+
+### Phase 4: Code Verification Checklist
+
+- [ ] All migrated files reviewed
+- [ ] All imports verified resolving
+- [ ] All cross-references updated
+- [ ] No behavioral changes detected
+- [ ] Existing tests pass with same results
+- [ ] Verification report generated
+- [ ] **systematic-debugging skill called (MANDATORY)**
+- [ ] All issues resolved
+
+### Phase 5: Archive & Test Checklist
+
+- [ ] Old structure moved to `archivecodes/`
+- [ ] New structure in place (no temporary prefixes)
+- [ ] Comprehensive unit tests written
+- [ ] **test-driven-development skill used (MANDATORY)**
+- [ ] All tests pass (100% success)
+- [ ] Coverage ≥ 80% (prefer 100%)
+- [ ] Documentation updated
+- [ ] Migration changelog created
+- [ ] **systematic-debugging skill called for final review (MANDATORY)**
+- [ ] **test-driven-development skill called for test review (MANDATORY)**
+
+## Anti-Patterns & Common Rationalizations
+
+### Common Rationalizations
+
+| Rationalization | Reality | Action |
+|----------------|---------|--------|
+| "Just this once, I'll add this small improvement" | Violation of Iron Law 2 - stop immediately | Delete improvement, re-migrate correctly |
+| "I'll refactor it properly later" | Later never comes - technical debt accumulates | Do it right now, or don't do it |
+| "This small feature won't affect the migration" | It violates exact migration principle | Feature creep = failed migration |
+| "Testing after migration is faster" | Untested migration is unverified migration | Use test-driven-development, no exceptions |
+| "systematic-debugging takes too long" | It's faster than debugging production issues | Quality gates are non-negotiable |
+| "The existing structure is close enough" | Partial compliance is non-compliance | Follow standard exactly |
+| "I'll fix the imports as I go" | Systematic approach prevents broken references | Update imports immediately after migration |
+| "This module is too simple to need TDD" | Simple code breaks too - TDD applies to all | Use test-driven-development for ALL code |
+| "While I'm here, I'll also fix X" | "While I'm here" anti-pattern | One task at a time, complete migration first |
+
+### Red Flags - STOP and Re-evaluate
+
+If you catch yourself thinking:
+- "This is a special case, I can adapt the rules"
+- "I don't need to call [skill], this is straightforward"
+- "Let me just add this quick improvement"
+- "I'll skip the quality gate to save time"
+- "This doesn't need to be tested"
+- "The structure is close enough"
+- "I'll document this deviation later"
+
+**ALL of these mean: STOP. You're violating the iron laws.**
+
+Return to the relevant phase and follow the process correctly.
+
+## Quality Gates
+
+### After Phase 3: Structure Migration
+1. Self-review checklist completed
+2. **Call systematic-debugging skill (MANDATORY)**
+3. All imports resolve correctly
+4. No syntax errors
+5. Existing tests pass
+
+### After Phase 4: Code Verification
+1. **Call systematic-debugging skill (MANDATORY)**
+2. All verification checks pass
+3. No behavioral changes
+4. All cross-references updated
+
+### After Phase 5: Archive & Test
+1. **Call systematic-debugging skill (MANDATORY)**
+2. **Call test-driven-development skill (MANDATORY)**
+3. All tests pass (100%)
+4. Coverage threshold met (≥80%)
+5. Documentation complete
+
+**No exceptions without explicit user override.**
+
+## Templates
+
+### Available Templates
+
+This skill includes supporting templates in `templates/`:
+
+1. **compliance-report.md**
+   - Use for Phase 1: Compliance Assessment
+   - Includes severity levels (CRITICAL/HIGH/MEDIUM/LOW)
+   - Structure for findings and recommendations
+
+2. **migration-plan.md**
+   - Use for Phase 2: Refactoring Planning
+   - Current structure documentation
+   - Migration mapping and sequencing
+   - Rollback plan
+
+3. **verification-checklist.md**
+   - Use for Phase 4: Code Verification
+   - Structure, imports, functionality checks
+   - Test coverage verification
+
+### Template Usage
+
+Templates include:
+- Required fields with guidance
+- Example structure
+- Validation reminders
+- Integration points with required skills
+
+## Example Workflow
+
+### Creating a New AI Project
+
+```
+User: "I want to create a new AI project for document processing"
+
+Assistant: (This skill activates)
+
+"I'll help you create a compliant AI project following LangGraph 1.0+ standards.
+
+First, let me create the standard directory structure:
+
+1. Create required directories (agents/, apps/, core/, configs/, models/, tests/)
+2. Create first agent with required subdirectories
+3. Call software-architecture skill for architectural validation
+4. Set up initial configuration files
+
+Then:
+- Use test-driven-development for any initial code
+- Ensure all architecture follows PROJECT_STRUCTURE.md
+
+Shall I proceed with creating the structure?"
+```
+
+### Reviewing Existing Project
+
+```
+User: "Review my AI project structure for compliance"
+
+Assistant: (This skill activates - Phase 1)
+
+"I'll analyze your project structure against PROJECT_STRUCTURE.md requirements.
+
+Scanning directories...
+Checking agent structure...
+Validating configuration...
+
+Generating compliance report...
+
+[Present report with severity levels]
+
+Found:
+- 3 CRITICAL issues (missing required directories)
+- 5 HIGH issues (incorrect agent structure)
+- 2 MEDIUM issues (naming violations)
+
+Recommendations:
+1. Address CRITICAL issues first (blocks development)
+2. Refactor agent structure to match standard
+3. Fix naming conventions
+
+Would you like me to create a migration plan (Phase 2)?"
+```
+
+## Version History
+
+| Version | Date | Owner | Change |
+|---|---|---|---|
+| v1.0.0 | 2026-01-13 | Claude Code | Initial skill implementation with LangGraph 1.0+ architecture compliance |