@dtt_siye/atool 1.4.0 → 1.6.0

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

@@ -96,537 +96,36 @@ This skill **depends on** and **must invoke** these skills:
 
 **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 |
+## Quick Workflow
+
+1. **Assess compliance** — Read `rules/compliance-check.md` for component classification and gap identification
+2. **Plan refactoring** — Read `rules/refactoring.md` for migration mapping and sequencing
+3. **Execute migration** — Read `rules/migration.md` for Iron Laws and step-by-step migration
+4. **Verify changes** — Read `rules/verification.md` for behavioral validation
+5. **Validate architecture** — Read `rules/architecture-validation.md` for structural checks
+6. **Ensure testing** — Read `rules/testing.md` for TDD requirements and coverage goals
+
+## File Reference Map
+
+| File | When to Read | Content |
+|------|-------------|---------|
+| `rules/compliance-check.md` | Assessing project structure | Component classification, Tier 1/2/3 requirements, gap analysis |
+| `rules/refactoring.md` | Planning migration | Migration mapping, sequencing, rollback strategy |
+| `rules/migration.md` | During structure migration | Iron Laws, execution steps, forbidden actions |
+| `rules/verification.md` | After migration | Code review, import validation, behavioral verification |
+| `rules/architecture-validation.md` | Structural validation | Architecture checks, naming conventions, separation of concerns |
+| `rules/iron-laws.md` | All phases | Core principles, red flags, violation handling |
+| `rules/testing.md` | Testing phase | TDD requirements, test types, quality gates |
+
+## Constraints
+
+- Must follow Iron Laws without exception
+- Must call required skills at specified points
+- Must work incrementally (single-agent batches)
+- Must achieve 80%+ test coverage
+- Must maintain exact functionality during migration
+- Must validate against PROJECT_STRUCTURE.md
+
+> IMPORTANT: When this skill is invoked, you MUST read the relevant
+> subdirectory files based on the current phase. Do NOT execute using
+> only this SKILL.md content.