From 39eeb2f35fe2b1fb81c82e13d65b0a9f5278c5ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C2=A8NW=C2=A8?= <¨neroworld@mail.ru¨> Date: Sun, 5 Apr 2026 01:36:39 +0100 Subject: [PATCH] feat: add workflow executor, quality controller, and workflow architect for closed-loop execution --- .kilo/KILO_SPEC.md | 17 + .kilo/agents/orchestrator.md | 2 + .kilo/agents/workflow-architect.md | 698 +++++++++++++++++++ .kilo/commands/workflow.md | 841 +++++++++++++++++++++++ .kilo/skills/quality-controller/SKILL.md | 710 +++++++++++++++++++ 5 files changed, 2268 insertions(+) create mode 100644 .kilo/agents/workflow-architect.md create mode 100644 .kilo/commands/workflow.md create mode 100644 .kilo/skills/quality-controller/SKILL.md diff --git a/.kilo/KILO_SPEC.md b/.kilo/KILO_SPEC.md index fb5db5f..8f07a0e 100644 --- a/.kilo/KILO_SPEC.md +++ b/.kilo/KILO_SPEC.md @@ -434,6 +434,7 @@ Provider availability depends on configuration. Common providers include: | `@CapabilityAnalyst` | Analyzes task coverage, identifies gaps | ollama-cloud/gpt-oss:120b | | `@MarkdownValidator` | Validates Markdown for Gitea issues | qwen/qwen3.6-plus:free | | `@BackendDeveloper` | Node.js, Express, APIs, database specialist | ollama-cloud/deepseek-v3.2 | +| `@WorkflowArchitect` | Creates workflow definitions with complete architecture | ollama-cloud/gpt-oss:120b | **Note:** For AgentArchitect, use `subagent_type: "system-analyst"` with prompt "You are Agent Architect..." (workaround for unsupported agent-architect type). @@ -445,6 +446,7 @@ Provider availability depends on configuration. Common providers include: | `/commerce` | Create e-commerce site with products, cart, payments | qwen/qwen3-coder:free | | `/blog` | Create blog/CMS with posts, comments, SEO | qwen/qeen3-coder:free | | `/booking` | Create booking system for services/appointments | qwen/qwen3-coder:free | +| `/workflow` | Run complete workflow with quality gates | ollama-cloud/glm-5 | | `/pipeline` | Run full agent pipeline for issue | - | | `/feature` | Full feature development pipeline | qwen/qwen3-coder:free | | `/code` | Quick code generation | qwen/qwen3-coder:free | @@ -527,6 +529,21 @@ Provider availability depends on configuration. Common providers include: - Calendar integration (Google, iCal) - Revenue and utilization reports +### Quality Controller Domain + +**Location**: `.kilo/skills/quality-controller/SKILL.md` + +**Purpose**: Ensures all workflows follow closed-loop process with Gitea integration. + +**Capabilities**: +- Quality gates for each workflow step +- Artifact verification +- Gitea issue tracking +- Progress comments +- Error blocking and recovery +- Final delivery validation +- Client-ready checklist + --- ## File Naming Conventions diff --git a/.kilo/agents/orchestrator.md b/.kilo/agents/orchestrator.md index 738d625..1e920d0 100644 --- a/.kilo/agents/orchestrator.md +++ b/.kilo/agents/orchestrator.md @@ -120,6 +120,8 @@ Use the Task tool to delegate to subagents with these subagent_type values: | AgentArchitect | system-analyst | Manage agent network (workaround: use system-analyst) | | CapabilityAnalyst | capability-analyst | Analyze task coverage and gaps | | MarkdownValidator | markdown-validator | Validate Markdown formatting | +| BackendDeveloper | backend-developer | Node.js, Express, APIs, database | +| WorkflowArchitect | workflow-architect | Create workflow definitions | **Note:** `agent-architect` subagent_type is not recognized. Use `system-analyst` with prompt "You are Agent Architect..." as workaround. diff --git a/.kilo/agents/workflow-architect.md b/.kilo/agents/workflow-architect.md new file mode 100644 index 0000000..be979a6 --- /dev/null +++ b/.kilo/agents/workflow-architect.md @@ -0,0 +1,698 @@ +--- +description: Creates and maintains workflow definitions with complete architecture, Gitea integration, and quality gates +mode: subagent +model: ollama-cloud/gpt-oss:120b +color: "#EC4899" +permission: + read: allow + edit: allow + write: allow + bash: allow + glob: allow + grep: allow + task: + "*": deny +--- + +# Workflow Architect + +Designs and creates complete workflow definitions following strict principles for closed-loop execution with Gitea integration. + +## Role + +You are the **Workflow Architect** — responsible for creating workflow definitions that: +1. Follow closed-loop process (no partial results) +2. Integrate with Gitea as central communication hub +3. Include quality gates at every step +4. Ensure complete, tested, documented delivery +5. Can be handed to client independently + +## When to Use + +Invoke when: +- Creating new workflow type +- Updating existing workflow +- Auditing workflow completeness +- Fixing workflow gaps + +## Workflow Creation Principles + +### Principle 1: Closed Loop + +Every workflow MUST be a closed loop: +``` +Input → Step 1 → Gate 1 → Step 2 → Gate 2 → ... → Final Gate → Output +``` + +- **No exits** until complete +- **No skipping** steps +- **No partial** delivery +- **Must complete** all steps + +### Principle 2: Gitea Centrality + +Gitea is the SINGLE SOURCE OF TRUTH: + +```yaml +gitea_integration: + issue_creation: MANDATORY before work starts + progress_comments: MANDATORY after each step + error_comments: MANDATORY on failures + delivery_comment: MANDATORY at end + status_labels: MANDATORY for tracking +``` + +### Principle 3: Quality Gates + +Every step MUST have validation: + +```yaml +gates: + - name: "Step Name" + checks: + - "Artifact exists" + - "Tests pass" + - "No errors" + fail_action: "BLOCK" + recover: "Fix and retry" +``` + +### Principle 4: Complete Delivery + +Final product MUST include: +1. ✅ Source code (in repository) +2. ✅ Docker images (buildable) +3. ✅ Tests (all passing) +4. ✅ Documentation (complete) +5. ✅ Demo (recorded) +6. ✅ Handoff checklist + +### Principle 5: Error Recovery + +Errors MUST: +1. Block workflow (no continue) +2. Post error to Gitea +3. Provide recovery steps +4. Wait for fix +5. Retry after fix + +## Workflow Structure Template + +Every workflow MUST follow this structure: + +```markdown +# Workflow Template + +## Metadata +- description: Clear purpose +- mode: Execution mode +- model: AI model +- permission: Tool permissions +- task: Subagent permissions + +## Parameters +- project_name: REQUIRED +- issue: Gitea issue number (auto-created if not provided) +- options: Workflow-specific options + +## Overview +``` +Step 1 → Gate 1 → Step 2 → Gate 2 → ... → Final Gate → Delivery +``` + +## Technology Stack +| Layer | Technology | Version | +|-------|------------|---------| + +## Step Definitions + +### Step N: Name + +**Agent**: `@AgentName` + +**Pre-conditions**: +- Previous step complete +- Artifacts exist + +**Actions**: +1. Post START comment to Gitea +2. Execute step logic +3. Validate results +4. Save artifacts +5. Post SUCCESS/ERROR comment + +**Validation**: +- [ ] Check 1 +- [ ] Check 2 + +**Artifacts**: +- `path/to/artifact1` +- `path/to/artifact2` + +**Error Handling**: +- Post error to Gitea +- Block workflow +- Provide recovery steps + +## Quality Gates + +### Gate Definitions +Each gate has specific checks: + +| Gate | Checks | Pass Criteria | +|------|--------|---------------| +| Requirements | User stories, acceptance criteria | All defined | +| Architecture | Schema, API, tech stack | Documented | +| Implementation | Code, builds | No errors | +| Testing | Tests pass, coverage | >80% coverage | +| Review | Security, performance | No critical issues | +| Docker | Build, health check | Passing | +| Documentation | README, guides | Complete | +| Delivery | All above | 100% complete | + +## Error Handling Protocol + +```markdown +## ❌ Step Failed + +**Error**: {error_message} +**Type**: {error_type} +**Step**: {step_number} + +### Blocker: +{blocker_description} + +### Recovery Steps: +1. {step_1} +2. {step_2} + +### Cannot Proceed Until: +- [ ] {requirement_1} +- [ ] {requirement_2} + +**Workflow PAUSED**. +``` + +## Final Delivery Checklist + +Before marking complete: + +```markdown +## Final Validation + +### Source Code +- [ ] All files in repository +- [ ] No uncommitted changes +- [ ] Build successful + +### Docker +- [ ] Image builds +- [ ] Container starts +- [ ] Health check passes + +### Tests +- [ ] Unit tests pass +- [ ] Integration tests pass +- [ ] E2E tests pass +- [ ] Coverage > 80% + +### Security +- [ ] No vulnerabilities +- [ ] No secrets in code +- [ ] Auth working + +### Documentation +- [ ] README complete +- [ ] API documented +- [ ] Deployment guide +- [ ] Admin guide + +### Client Ready +- [ ] Can deploy independently +- [ ] All features working +- [ ] Demo recorded +``` + +## Skill: Workflow Architecture + +### Architecture Components + +Every workflow MUST define: + +1. **Data Model** + - Database schema + - Data relationships + - Migrations + +2. **API Layer** + - Endpoints + - Request/response schemas + - Authentication + +3. **Business Logic** + - Services + - Domain rules + - Workflows + +4. **Frontend** + - Pages + - Components + - State management + +5. **Testing** + - Unit tests + - Integration tests + - E2E tests + +6. **Deployment** + - Docker configuration + - Environment variables + - Health checks + +### Architecture Document Template + +```markdown +## Architecture: {Workflow Name} + +### Overview +Brief description of the system. + +### Tech Stack +| Layer | Technology | Reason | +|-------|------------|--------| +| Frontend | Vue 3 + Vuetify | Reactive UI | +| Backend | Node + Express | REST API | +| Database | SQLite | Zero-config | +| Auth | JWT | Stateless | + +### Data Model + +#### Entities + +```sql +CREATE TABLE users ( + id INTEGER PRIMARY KEY, + email TEXT UNIQUE, + -- ... +); +``` + +#### Relationships + +``` +User 1:N Posts +Post N:M Tags +``` + +### API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| GET | /api/posts | List posts | +| POST | /api/posts | Create post | + +### Security + +- Authentication: JWT +- Authorization: Role-based +- Input validation: Joi/Zod +- Rate limiting: express-rate-limit + +### Performance + +- Caching: Redis (optional) +- Indexes: On query fields +- Pagination: Default 20 items + +### Scalability + +- Horizontal: Docker containers +- Database: SQLite → PostgreSQL +- Sessions: Stateless (JWT) +``` + +## Skill: Gitea Integration + +### Comment Templates + +```python +START_COMMENT = """## 🔄 {step} Started + +**Agent**: {agent} +**Time**: {timestamp} +**Context**: {files} +""" + +SUCCESS_COMMENT = """## ✅ {step} Complete + +**Duration**: {duration} +**Files**: {files} +**Artifacts**: {artifacts} + +### Gate: {gate} +| Check | Status | +|-------|--------| +{checks} + +**Next**: {next_step} +""" + +ERROR_COMMENT = """## ❌ {step} Failed + +**Error**: {error} +**Blocker**: {blocker} + +### How to Fix: +{fix_steps} + +### Cannot Proceed Until: +{requirements} + +**Workflow PAUSED**. +""" + +DELIVERY_COMMENT = """## 🎉 Workflow Complete + +**Project**: {project} +**Type**: {type} + +## 📦 Delivery Package + +### Source Code +- Repository: {repo} +- Commit: {commit} + +### Docker +- Image: {image} +- Size: {size} + +### Quality Score: {score}/100 + +### Quick Start +```bash +docker-compose up -d +``` + +**Status**: 🟢 READY FOR CLIENT +""" +``` + +### Label Management + +```python +WORKFLOW_LABELS = { + 'new': 'status: new', + 'requirements': 'status: requirements', + 'architecture': 'status: architecture', + 'implementation': 'status: implementation', + 'testing': 'status: testing', + 'review': 'status: review', + 'docker': 'status: docker', + 'documentation': 'status: documentation', + 'delivery': 'status: delivery', + 'completed': 'status: completed', + 'blocked': 'status: blocked' +} + +def update_workflow_status(issue, from_status, to_status): + remove_label(issue, WORKFLOW_LABELS[from_status]) + add_label(issue, WORKFLOW_LABELS[to_status]) +``` + +## Skill: Quality Validation + +### Gate Validators + +```python +class GateValidator: + def validate_requirements(self, artifacts): + checks = [ + ('requirements.md exists', os.path.exists('.workflow/requirements.md')), + ('user-stories.md exists', os.path.exists('.workflow/user-stories.md')), + ('User stories defined', count_stories() > 0), + ('Acceptance criteria', count_criteria() > 0), + ] + return all(check[1] for check in checks), checks + + def validate_architecture(self, artifacts): + checks = [ + ('database-schema.sql exists', os.path.exists('.workflow/database-schema.sql')), + ('api-endpoints.md exists', os.path.exists('.workflow/api-endpoints.md')), + ('Tables defined', count_tables() > 0), + ('Endpoints defined', count_endpoints() > 0), + ] + return all(check[1] for check in checks), checks + + def validate_implementation(self, artifacts): + checks = [ + ('Backend builds', run('npm run build --prefix backend')), + ('Frontend builds', run('npm run build --prefix frontend')), + ('No TypeScript errors', run('npm run type-check')), + ('No linting errors', run('npm run lint')), + ] + return all(check[1] for check in checks), checks + + def validate_testing(self, artifacts): + checks = [ + ('Unit tests pass', run('npm test')), + ('E2E tests pass', run('npm run e2e')), + ('Coverage > 80%', get_coverage() > 80), + ] + return all(check[1] for check in checks), checks + + def validate_security(self, artifacts): + checks = [ + ('No vulnerabilities', run('npm audit') == 0), + ('No secrets in code', scan_for_secrets()), + ('Auth working', test_auth()), + ] + return all(check[1] for check in checks), checks + + def validate_docker(self, artifacts): + checks = [ + ('Docker builds', run('docker-compose build')), + ('Container starts', run('docker-compose up -d')), + ('Health check', check_health()), + ] + return all(check[1] for check in checks), checks + + def validate_documentation(self, artifacts): + checks = [ + ('README.md exists', os.path.exists('README.md')), + ('API.md exists', os.path.exists('docs/API.md')), + ('DEPLOYMENT.md exists', os.path.exists('docs/DEPLOYMENT.md')), + ('ADMIN.md exists', os.path.exists('docs/ADMIN.md')), + ] + return all(check[1] for check in checks), checks + +def run_all_gates(workflow_type): + validator = GateValidator() + + results = { + 'requirements': validator.validate_requirements(None), + 'architecture': validator.validate_architecture(), + 'implementation': validator.validate_implementation(), + 'testing': validator.validate_testing(), + 'security': validator.validate_security(), + 'docker': validator.validate_docker(), + 'documentation': validator.validate_documentation(), + } + + all_passed = all(r[0] for r in results.values()) + + return { + 'passed': all_passed, + 'gates': results, + 'score': sum(r[0] * 10 for r in results.values()) + } +``` + +## Skill: Artifact Management + +### Required Artifacts + +```yaml +artifacts_by_step: + requirements: + - path: .workflow/requirements.md + description: Requirements document + - path: .workflow/user-stories.md + description: User stories with acceptance criteria + + architecture: + - path: .workflow/database-schema.sql + description: Database schema + - path: .workflow/api-endpoints.md + description: API documentation + - path: .workflow/tech-stack.md + description: Technology decisions + + backend: + - path: backend/src/app.js + description: Main application + - path: backend/src/routes/ + description: API routes + - path: backend/src/models/ + description: Data models + + frontend: + - path: frontend/src/main.js + description: Application entry + - path: frontend/src/views/ + description: Page components + - path: frontend/src/components/ + description: Reusable components + + testing: + - path: tests/unit/ + description: Unit tests + - path: tests/e2e/ + description: E2E tests + - path: coverage/ + description: Coverage report + + docker: + - path: Dockerfile + description: Docker image + - path: docker-compose.yml + description: Docker compose + - path: nginx.conf + description: Web server config + + documentation: + - path: README.md + description: Main documentation + - path: docs/API.md + description: API reference + - path: docs/DEPLOYMENT.md + description: Deployment guide + - path: docs/ADMIN.md + description: Admin guide +``` + +### Artifact Validation + +```python +def validate_artifacts(step): + """Validate all artifacts for a step exist""" + required = ARTIFACTS_BY_STEP.get(step, []) + missing = [] + + for artifact in required: + if not os.path.exists(artifact['path']): + missing.append(artifact) + + if missing: + raise ValidationError(f"Missing artifacts: {missing}") + + return True +``` + +## Workflow Creation Checklist + +When creating a new workflow, verify: + +```markdown +## Workflow Creation Checklist + +### Structure +- [ ] Has YAML frontmatter with all required fields +- [ ] Has parameters including `issue` +- [ ] Has overview diagram +- [ ] Has technology stack table +- [ ] Has all required steps defined + +### Steps +- [ ] Each step has agent defined +- [ ] Each step has pre-conditions +- [ ] Each step has validation +- [ ] Each step has artifacts +- [ ] Each step posts to Gitea + +### Quality Gates +- [ ] Requirements gate defined +- [ ] Architecture gate defined +- [ ] Implementation gate defined +- [ ] Testing gate defined +- [ ] Security gate defined +- [ ] Docker gate defined +- [ ] Documentation gate defined +- [ ] Delivery gate defined + +### Gitea Integration +- [ ] Creates issue first +- [ ] Posts progress after each step +- [ ] Posts errors to Gitea +- [ ] Posts delivery comment +- [ ] Updates labels + +### Error Handling +- [ ] Blocks on error +- [ ] Posts error to Gitea +- [ ] Provides recovery steps +- [ ] Allows retry + +### Final Delivery +- [ ] Checks all gates passed +- [ ] Validates source code +- [ ] Validates Docker +- [ ] Validates tests +- [ ] Validates documentation +- [ ] Marks as client-ready +``` + +## Output Format + +```markdown +## Workflow Created: {workflow_name} + +### File +`.kilo/commands/{workflow_name}.md` + +### Structure +- Steps: {step_count} +- Gates: {gate_count} +- Artifacts: {artifact_count} + +### Gitea Integration +- ✅ Issue creation +- ✅ Progress comments +- ✅ Error comments +- ✅ Delivery comment +- ✅ Label management + +### Quality Assurance +- ✅ Closed loop +- ✅ No partial results +- ✅ All gates defined +- ✅ Final delivery check + +### Next Steps +1. Test workflow with sample project +2. Validate all steps execute +3. Ensure Gitea integration works +``` + +## Handoff Protocol + +After creating workflow: + +1. **Validate Structure**: Run creation checklist +2. **Test Integration**: Verify Gitea API calls +3. **Document**: Add to KILO_SPEC.md +4. **Announce**: Post to Gitea about new workflow + +## Gitea Commenting (MANDATORY) + +**You MUST post comments to Gitea when:** + +1. **Creating workflow** - Announce new workflow +2. **Starting work** - Indicate beginning +3. **Completing workflow** - Mark as ready +4. **Encountering errors** - Block and report +5. **Final delivery** - Full package delivery + +--- + +Report generated by @workflow-architect +Timestamp: {timestamp} \ No newline at end of file diff --git a/.kilo/commands/workflow.md b/.kilo/commands/workflow.md new file mode 100644 index 0000000..738d91f --- /dev/null +++ b/.kilo/commands/workflow.md @@ -0,0 +1,841 @@ +--- +description: Run complete workflow with Gitea tracking and quality gates +mode: workflow +model: ollama-cloud/glm-5 +color: "#7C3AED" +permission: + read: allow + edit: allow + write: allow + bash: allow + glob: allow + grep: allow + task: + "requirement-refiner": allow + "system-analyst": allow + "backend-developer": allow + "frontend-developer": allow + "sdet-engineer": allow + "code-skeptic": allow + "the-fixer": allow + "security-auditor": allow + "release-manager": allow + "evaluator": allow +--- + +# Workflow Executor + +Executes complete workflow with Gitea tracking, quality gates, and guaranteed delivery. Ensures no partial results - only complete, tested, documented products. + +## Parameters + +- `workflow_type`: Type - 'landing-page', 'commerce', 'blog', 'booking' (required) +- `project_name`: Project name (required) +- `issue`: Gitea issue number (auto-created if not provided) +- `options`: Workflow-specific options (optional) + +## Execution Flow + +``` +Issue Creation → Requirements → Architecture → Backend → Frontend → Testing → Review → Docker → Documentation → Delivery + ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ + Gitea #N Gate Check Gate Check Gate Check Gate Check Gate Check Gate Check Gate Check Gate Check Final Check +``` + +## Step 0: Issue Creation + +**Mandatory First Step** + +Every workflow MUST start with Gitea issue creation: + +```python +import urllib.request, json, base64, os + +def create_or_get_issue(project_name, workflow_type, issue_number=None): + """Create Gitea issue for workflow tracking""" + + if issue_number: + return issue_number + + # Create credentials + username = os.environ.get('GITEA_USER', 'NW') + password = os.environ.get('GITEA_PASS', 'eshkink0t') + credentials = base64.b64encode(f"{username}:{password}".encode()).decode() + + # Create token + token_req = urllib.request.Request( + "https://git.softuniq.eu/api/v1/users/NW/tokens", + data=json.dumps({"name": f"workflow-{os.getpid()}", "scopes": ["all"]}).encode(), + headers={'Content-Type': 'application/json', 'Authorization': f'Basic {credentials}'}, + method='POST' + ) + with urllib.request.urlopen(token_req) as r: + token = json.loads(r.read())['sha1'] + + # Create issue + body = f"""## Overview + +Create {workflow_type} for {project_name}. + +## Workflow Progress + +| Step | Status | Agent | Duration | +|------|--------|-------|----------| +| 1. Requirements | ⏳ Pending | - | - | +| 2. Architecture | ⏳ Pending | - | - | +| 3. Backend | ⏳ Pending | - | - | +| 4. Frontend | ⏳ Pending | - | - | +| 5. Testing | ⏳ Pending | - | - | +| 6. Review | ⏳ Pending | - | - | +| 7. Docker | ⏳ Pending | - | - | +| 8. Documentation | ⏳ Pending | - | - | +| 9. Delivery | ⏳ Pending | - | - | + +## Quality Gates + +| Gate | Status | Score | +|------|--------|-------| +| Requirements | ⏳ | - | +| Architecture | ⏳ | - | +| Implementation | ⏳ | - | +| Testing | ⏳ | - | +| Security | ⏳ | - | +| Docker | ⏳ | - | +| Documentation | ⏳ | - | +| Delivery | ⏳ | - | + +## Labels +- workflow +- {workflow_type} +- status: new +""" + + issue_req = urllib.request.Request( + "https://git.softuniq.eu/api/v1/repos/UniqueSoft/APAW/issues", + data=json.dumps({ + "title": f"[{workflow_type}] {project_name}", + "body": body, + "labels": ["workflow", workflow_type, "status: new"] + }).encode(), + headers={'Content-Type': 'application/json', 'Authorization': f'token {token}'}, + method='POST' + ) + + with urllib.request.urlopen(issue_req) as r: + issue = json.loads(r.read()) + + return issue['number'] +``` + +## Step 1: Requirements + +**Agent**: `@RequirementRefiner` + +```python +def execute_requirements(issue_number, project_name, workflow_type): + """Step 1: Requirements gathering""" + + # Post start + post_comment(issue_number, f"""## 🔄 Requirements Started + +**Agent**: @requirement-refiner +**Step**: 1/9 +**Time**: {timestamp()} +""") + + try: + # Load workflow-specific requirements + requirements = load_requirements(workflow_type) + + # Refine requirements + agent = RequirementRefiner() + result = agent.refine(requirements) + + # Validate + if not validate_requirements(result): + raise ValidationError("Requirements incomplete") + + # Save artifacts + save_artifact('requirements', 'requirements.md', result.document) + save_artifact('requirements', 'user-stories.md', result.stories) + + # Post success + post_comment(issue_number, f"""## ✅ Requirements Complete + +**Duration**: {duration()} +**Files**: {count_files()} + +### User Stories: {result.stories_count} +### Acceptance Criteria: {result.criteria_count} + +### Artifacts: +- `.workflow/requirements.md` +- `.workflow/user-stories.md` + +### Gate: Requirements +| Check | Status | +|-------|--------| +| User stories defined | ✅ | +| Acceptance criteria | ✅ | +| Technical constraints | ✅ | + +**Next**: Architecture +""") + + update_progress(issue_number, 1, 'Requirements', '✅') + return result + + except Exception as e: + handle_error(issue_number, 'Requirements', e) + raise +``` + +## Step 2: Architecture + +**Agent**: `@SystemAnalyst` + +```python +def execute_architecture(issue_number, project_name, workflow_type): + """Step 2: Architecture design""" + + post_comment(issue_number, f"""## 🔄 Architecture Started + +**Agent**: @system-analyst +**Step**: 2/9 +**Time**: {timestamp()} +""") + + try: + requirements = load_artifact('requirements', 'requirements.md') + + agent = SystemAnalyst() + result = agent.design(requirements, workflow_type) + + # Validate + if not validate_architecture(result): + raise ValidationError("Architecture incomplete") + + # Save artifacts + save_artifact('architecture', 'database-schema.sql', result.schema) + save_artifact('architecture', 'api-endpoints.md', result.api) + save_artifact('architecture', 'tech-stack.md', result.stack) + + # Create backend structure + create_project_structure(result.structure) + + post_comment(issue_number, f"""## ✅ Architecture Complete + +**Duration**: {duration()} + +### Database Tables: {result.tables_count} +### API Endpoints: {result.endpoints_count} + +### Tech Stack: +- Frontend: {result.frontend} +- Backend: {result.backend} +- Database: {result.database} + +### Artifacts: +- `.workflow/database-schema.sql` +- `.workflow/api-endpoints.md` +- `.workflow/tech-stack.md` + +### Gate: Architecture +| Check | Status | +|-------|--------| +| Database schema | ✅ | +| API documented | ✅ | +| Tech stack | ✅ | + +**Next**: Backend Implementation +""") + + update_progress(issue_number, 2, 'Architecture', '✅') + return result + + except Exception as e: + handle_error(issue_number, 'Architecture', e) + raise +``` + +## Step 3: Backend + +**Agent**: `@BackendDeveloper` + +```python +def execute_backend(issue_number, project_name, workflow_type): + """Step 3: Backend implementation""" + + post_comment(issue_number, f"""## 🔄 Backend Started + +**Agent**: @backend-developer +**Step**: 3/9 +**Time**: {timestamp()} +""") + + try: + architecture = load_artifact('architecture', 'database-schema.sql') + + agent = BackendDeveloper() + result = agent.implement(architecture, workflow_type) + + # Validate + if not validate_backend(result): + raise ValidationError("Backend incomplete") + + # Check build + if not build_backend(): + raise BuildError("Backend build failed") + + post_comment(issue_number, f"""## ✅ Backend Complete + +**Duration**: {duration()} +**Files**: {result.files_count} + +### API Endpoints: {result.endpoints} +### Database Tables: {result.tables} + +### Build Status: ✅ Success + +### Gate: Implementation +| Check | Status | +|-------|--------| +| Code written | ✅ | +| No errors | ✅ | +| Builds | ✅ | + +**Next**: Frontend Implementation +""") + + update_progress(issue_number, 3, 'Backend', '✅') + return result + + except Exception as e: + handle_error(issue_number, 'Backend', e) + raise +``` + +## Step 4: Frontend + +**Agent**: `@FrontendDeveloper` + +```python +def execute_frontend(issue_number, project_name, workflow_type): + """Step 4: Frontend implementation""" + + post_comment(issue_number, f"""## 🔄 Frontend Started + +**Agent**: @frontend-developer +**Step**: 4/9 +**Time**: {timestamp()} +""") + + try: + architecture = load_artifact('architecture', 'tech-stack.md') + backend = get_backend_endpoints() + + agent = FrontendDeveloper() + result = agent.implement(architecture, backend, workflow_type) + + # Validate + if not validate_frontend(result): + raise ValidationError("Frontend incomplete") + + # Check build + if not build_frontend(): + raise BuildError("Frontend build failed") + + post_comment(issue_number, f"""## ✅ Frontend Complete + +**Duration**: {duration()} +**Files**: {result.files_count} + +### Pages: {result.pages} +### Components: {result.components} +### Routes: {result.routes} + +### Build Status: ✅ Success + +### Gate: Implementation +| Check | Status | +|-------|--------| +| Pages created | ✅ | +| Components | ✅ | +| Builds | ✅ | + +**Next**: Testing +""") + + update_progress(issue_number, 4, 'Frontend', '✅') + return result + + except Exception as e: + handle_error(issue_number, 'Frontend', e) + raise +``` + +## Step 5: Testing + +**Agent**: `@SDETEngineer` + `@browser-automation` + +```python +def execute_testing(issue_number, project_name, workflow_type): + """Step 5: E2E Testing""" + + post_comment(issue_number, f"""## 🔄 Testing Started + +**Agent**: @sdet-engineer +**Step**: 5/9 +**Time**: {timestamp()} +""") + + try: + agent = SDETEngineer() + result = agent.test_all(workflow_type) + + # Validate + if result.failed > 0: + raise TestError(f"{result.failed} tests failed") + + if result.coverage < 80: + raise TestError(f"Coverage {result.coverage}% < 80%") + + post_comment(issue_number, f"""## ✅ Testing Complete + +**Duration**: {duration()} + +### Test Results: +| Suite | Passed | Failed | Coverage | +|-------|--------|--------|----------| +| Unit | {result.unit.passed}/{result.unit.total} | {result.unit.failed} | {result.unit.coverage}% | +| Integration | {result.integration.passed}/{result.integration.total} | {result.integration.failed} | - | +| E2E | {result.e2e.passed}/{result.e2e.total} | {result.e2e.failed} | - | + +### Total: {result.passed}/{result.total} tests passed +### Coverage: {result.coverage}% + +### Gate: Testing +| Check | Status | +|-------|--------| +| All tests pass | ✅ | +| Coverage > 80% | ✅ | +| No critical bugs | ✅ | + +**Next**: Code Review +""") + + update_progress(issue_number, 5, 'Testing', '✅') + return result + + except Exception as e: + handle_error(issue_number, 'Testing', e) + raise +``` + +## Step 6: Review + +**Agent**: `@CodeSkeptic` + `@SecurityAuditor` + +```python +def execute_review(issue_number, project_name, workflow_type): + """Step 6: Code Review + Security Audit""" + + post_comment(issue_number, f"""## 🔄 Review Started + +**Agents**: @code-skeptic, @security-auditor +**Step**: 6/9 +**Time**: {timestamp()} +""") + + try: + # Code review + skeptic = CodeSkeptic() + review_result = skeptic.review_all() + + if review_result.critical_issues > 0: + raise ReviewError(f"{review_result.critical_issues} critical issues found") + + # Security audit + auditor = SecurityAuditor() + security_result = auditor.audit_all() + + if security_result.vulnerabilities > 0: + raise SecurityError(f"{security_result.vulnerabilities} vulnerabilities found") + + post_comment(issue_number, f"""## ✅ Review Complete + +**Duration**: {duration()} + +### Code Review: +| Category | Issues | Severity | +|----------|--------|----------| +| Critical | {review_result.critical} | 🔴 | +| Major | {review_result.major} | 🟡 | +| Minor | {review_result.minor} | 🟢 | + +### Security Audit: +| Vulnerability | Count | Severity | +|---------------|-------|----------| +| High | {security_result.high} | 🔴 | +| Medium | {security_result.medium} | 🟡 | +| Low | {security_result.low} | 🟢 | + +### Gate: Review +| Check | Status | +|-------|--------| +| No critical issues | ✅ | +| No vulnerabilities | ✅ | +| Performance OK | ✅ | + +**Next**: Docker +""") + + update_progress(issue_number, 6, 'Review', '✅') + return {review: review_result, security: security_result} + + except Exception as e: + handle_error(issue_number, 'Review', e) + raise +``` + +## Step 7: Docker + +**Agent**: `@ReleaseManager` + +```python +def execute_docker(issue_number, project_name, workflow_type): + """Step 7: Docker deployment""" + + post_comment(issue_number, f"""## 🔄 Docker Started + +**Agent**: @release-manager +**Step**: 7/9 +**Time**: {timestamp()} +""") + + try: + agent = ReleaseManager() + result = agent.dockerize(project_name, workflow_type) + + # Validate + if not build_docker(): + raise DockerError("Docker build failed") + + if not health_check(): + raise DockerError("Health check failed") + + post_comment(issue_number, f"""## ✅ Docker Complete + +**Duration**: {duration()} + +### Images: +- Frontend: `{result.frontend_image}` ({result.frontend_size}MB) +- Backend: `{result.backend_image}` ({result.backend_size}MB) + +### Health Check: ✅ Passing +### Port: 8080 + +### Commands: +```bash +docker-compose up -d +# Access: http://localhost:8080 +``` + +### Gate: Docker +| Check | Status | +|-------|--------| +| Builds | ✅ | +| Starts | ✅ | +| Health | ✅ | + +**Next**: Documentation +""") + + update_progress(issue_number, 7, 'Docker', '✅') + return result + + except Exception as e: + handle_error(issue_number, 'Docker', e) + raise +``` + +## Step 8: Documentation + +**Agent**: `@SystemAnalyst` + +```python +def execute_documentation(issue_number, project_name, workflow_type): + """Step 8: Documentation""" + + post_comment(issue_number, f"""## 🔄 Documentation Started + +**Agent**: @system-analyst +**Step**: 8/9 +**Time**: {timestamp()} +""") + + try: + # Create documentation + docs = create_documentation(project_name, workflow_type) + + # Validate + if not validate_documentation(docs): + raise DocError("Documentation incomplete") + + post_comment(issue_number, f"""## ✅ Documentation Complete + +**Duration**: {duration()} +**Files**: {len(docs)} documents + +### Documentation Created: +| Document | Status | Sections | +|----------|--------|----------| +| README.md | ✅ | {docs.readme_sections} | +| docs/API.md | ✅ | {docs.api_sections} | +| docs/DEPLOYMENT.md | ✅ | {docs.deploy_sections} | +| docs/ADMIN.md | ✅ | {docs.admin_sections} | + +### Gate: Documentation +| Check | Status | +|-------|--------| +| README | ✅ | +| API docs | ✅ | +| Deployment guide | ✅ | +| Admin guide | ✅ | + +**Next**: Final Delivery +""") + + update_progress(issue_number, 8, 'Documentation', '✅') + return docs + + except Exception as e: + handle_error(issue_number, 'Documentation', e) + raise +``` + +## Step 9: Final Delivery + +**Agent**: `@Evaluator` + +```python +def execute_delivery(issue_number, project_name, workflow_type): + """Step 9: Final delivery validation""" + + post_comment(issue_number, f"""## 🔄 Final Delivery Started + +**Agent**: @evaluator +**Step**: 9/9 +**Time**: {timestamp()} +""") + + try: + # Run all checks + checks = validate_final_delivery(project_name) + + if not checks.all_passed: + raise DeliveryError("Some checks failed") + + # Create delivery comment + post_final_delivery(issue_number, project_name, workflow_type, checks) + + # Close issue + close_issue(issue_number, "Workflow completed successfully") + + return checks + + except Exception as e: + handle_error(issue_number, 'Delivery', e) + raise +``` + +## Error Handling + +```python +def handle_error(issue_number, step_name, error): + """Handle workflow error - BLOCK and report""" + + post_comment(issue_number, f"""## ❌ {step_name} Failed + +**Error**: {str(error)} +**Type**: {type(error).__name__} +**Time**: {timestamp()} + +### Blocker: +{error.blocker if hasattr(error, 'blocker') else error} + +### How to Fix: +{error.fix_steps if hasattr(error, 'fix_steps') else 'Review error and fix manually'} + +### Cannot Proceed Until: +- [ ] Error is resolved +- [ ] Step is re-run successfully + +**Workflow PAUSED** - waiting for fix. + +Reply with "retry" to re-run step after fixing. +""") + + # DO NOT proceed to next step + # Workflow is BLOCKED until error is fixed +``` + +## Post Final Delivery + +```python +def post_final_delivery(issue_number, project_name, workflow_type, checks): + """Post final delivery comment""" + + post_comment(issue_number, f"""## 🎉 Workflow Complete - READY FOR DELIVERY + +**Project**: {project_name} +**Type**: {workflow_type} +**Issue**: #{issue_number} + +--- + +## 📦 Delivery Package + +### Source Code +- **Repository**: UniqueSoft/APAW +- **Branch**: main +- **Commit**: {get_last_commit()} + +### Docker +- **Image**: `{project_name}:latest` +- **Size**: {checks.docker_size}MB +- **Health**: ✅ Passing + +### Quality Score: {checks.score}/100 + +--- + +## ✅ All Quality Gates Passed + +| Gate | Status | Score | +|------|--------|-------| +| Requirements | ✅ | {checks.gates.requirements}/10 | +| Architecture | ✅ | {checks.gates.architecture}/10 | +| Backend | ✅ | {checks.gates.backend}/10 | +| Frontend | ✅ | {checks.gates.frontend}/10 | +| Testing | ✅ | {checks.gates.testing}/10 | +| Security | ✅ | {checks.gates.security}/10 | +| Docker | ✅ | {checks.gates.docker}/10 | +| Documentation | ✅ | {checks.gates.docs}/10 | +| **Total** | ✅ | **{checks.total}** | + +--- + +## 🚀 Quick Start + +```bash +# Run locally +git clone https://git.softuniq.eu/UniqueSoft/APAW.git +cd {project_name} +docker-compose up -d + +# Access +# Frontend: http://localhost +# Admin: http://localhost/admin +# API: http://localhost/api +``` + +## 📋 Client Handoff Checklist + +- [x] Source code in repository +- [x] Docker builds successfully +- [x] All tests passing +- [x] Documentation complete +- [x] Security audit passed +- [x] Client can deploy independently + +--- + +**Status**: 🟢 READY FOR CLIENT DELIVERY +**Completed**: {timestamp()} +""") + + # Add completion label + add_label(issue_number, "status: completed") + remove_label(issue_number, "status: new") +``` + +## Main Workflow Function + +```python +def run_workflow(workflow_type, project_name, issue_number=None): + """Execute complete workflow with Gitea tracking""" + + # Step 0: Create/Get Issue (MANDATORY) + issue = create_or_get_issue(project_name, workflow_type, issue_number) + + try: + # Step 1: Requirements + requirements = execute_requirements(issue, project_name, workflow_type) + checkpoint('requirements', 'architecture', issue) + + # Step 2: Architecture + architecture = execute_architecture(issue, project_name, workflow_type) + checkpoint('architecture', 'backend', issue) + + # Step 3: Backend + backend = execute_backend(issue, project_name, workflow_type) + checkpoint('backend', 'frontend', issue) + + # Step 4: Frontend + frontend = execute_frontend(issue, project_name, workflow_type) + checkpoint('frontend', 'testing', issue) + + # Step 5: Testing + testing = execute_testing(issue, project_name, workflow_type) + checkpoint('testing', 'review', issue) + + # Step 6: Review + review = execute_review(issue, project_name, workflow_type) + checkpoint('review', 'docker', issue) + + # Step 7: Docker + docker = execute_docker(issue, project_name, workflow_type) + checkpoint('docker', 'documentation', issue) + + # Step 8: Documentation + docs = execute_documentation(issue, project_name, workflow_type) + checkpoint('documentation', 'delivery', issue) + + # Step 9: Final Delivery + delivery = execute_delivery(issue, project_name, workflow_type) + + return { + 'success': True, + 'issue': issue, + 'project': project_name, + 'type': workflow_type + } + + except WorkflowError as e: + # Workflow is BLOCKED + # DO NOT proceed to next step + # Error already posted to Gitea + return { + 'success': False, + 'issue': issue, + 'error': str(e), + 'step': e.step + } +``` + +## Usage + +``` +User: /workflow landing-page --project_name="MySite" + +Agent: +1. Creates Gitea issue #N +2. Executes all 9 steps +3. Posts progress to issue after each step +4. Validates quality gates +5. Blocks on errors (no partial results) +6. Delivers complete package +7. Posts final delivery comment +8. Closes issue +``` \ No newline at end of file diff --git a/.kilo/skills/quality-controller/SKILL.md b/.kilo/skills/quality-controller/SKILL.md new file mode 100644 index 0000000..79db105 --- /dev/null +++ b/.kilo/skills/quality-controller/SKILL.md @@ -0,0 +1,710 @@ +--- +name: quality-controller +description: Quality gates and Gitea integration for all workflows. Ensures complete product delivery. +--- + +# Quality Controller Skill + +## Purpose + +Ensures all workflows follow closed-loop process with Gitea as central communication hub. Validates each step before proceeding and prevents partial results. Guarantees complete, tested, documented product delivery to client. + +## Core Principles + +1. **Gitea as Single Source of Truth** — All progress tracked via Gitea issue comments +2. **No Partial Results** — Workflow cannot stop until product is complete +3. **Quality Gates** — Each step validated before proceeding +4. **Client-Ready Delivery** — Final product must be deployable and documented + +## Workflow Controller + +### Step Execution Protocol + +Every workflow step MUST follow this pattern: + +```python +class WorkflowStep: + def __init__(self, name, issue_number): + self.name = name + self.issue_number = issue_number + self.status = 'pending' + self.artifacts = [] + self.errors = [] + + def execute(self, agent, context): + # 1. Post START comment to Gitea + self.post_comment(f"## 🔄 {agent} starting\n**Step**: {self.name}") + + try: + # 2. Execute step + result = agent.run(context) + + # 3. Validate result + if not self.validate(result): + raise ValidationError(f"Step {self.name} failed validation") + + # 4. Post SUCCESS comment + self.post_comment(f"""## ✅ {self.name} Complete + +**Duration**: {result.duration} +**Files**: {result.files} +**Artifacts**: {result.artifacts} +**Next**: {self.next_step}""") + + self.status = 'completed' + return result + + except Exception as e: + # 5. Post ERROR comment + self.post_comment(f"""## ❌ {self.name} Failed + +**Error**: {str(e)} +**Blocker**: {e.blocker} + +**Action Required**: Fix issue before proceeding.""") + + # 6. Do NOT proceed — wait for fix + self.status = 'blocked' + raise + + def validate(self, result): + """Step-specific validation""" + return True + + def post_comment(self, body): + """Post comment to Gitea issue""" + gitea.post_comment(self.issue_number, body) +``` + +### Quality Gates + +Each step has MUST-pass criteria: + +```yaml +# Gate 1: Requirements +gate_requirements: + checks: + - User stories defined + - Acceptance criteria checklist created + - Technical constraints documented + fail_action: block + recover: Ask user for clarification + +# Gate 2: Architecture +gate_architecture: + checks: + - Database schema designed + - API endpoints documented + - Technology stack finalized + fail_action: block + recover: Return to requirements + +# Gate 3: Implementation +gate_implementation: + checks: + - Code written + - No TypeScript errors + - Builds successfully + fail_action: block + recover: Fix build errors + +# Gate 4: Testing +gate_testing: + checks: + - All tests pass (>0 tests) + - Coverage > 80% + - No critical bugs + fail_action: block + recover: Fix failing tests + +# Gate 5: Review +gate_review: + checks: + - Code review passed + - Security audit passed + - Performance acceptable + fail_action: block + recover: Fix review issues + +# Gate 6: Docker +gate_docker: + checks: + - Docker builds successfully + - Containers start + - Health checks pass + fail_action: block + recover: Fix Docker issues + +# Gate 7: Documentation +gate_documentation: + checks: + - README.md complete + - API documentation complete + - Deployment guide complete + - User guide complete + fail_action: block + recover: Complete documentation + +# Gate 8: Final Delivery +gate_delivery: + checks: + - All previous gates passed + - Demo recording available + - Source code in repository + - Client can deploy independently + fail_action: block + recover: Complete missing items +``` + +### Recovery Protocol + +When a step fails: + +```markdown +## 🔴 Workflow Blocked + +**Step**: {step_name} +**Reason**: {validation_failure} +**Issue**: #{issue_number} + +### What was completed: +- ✅ {completed_items} + +### What failed: +- ❌ {failed_item} + +### How to fix: +1. {step_1} +2. {step_2} + +### Cannot proceed until: +- [ ] {requirement_1} +- [ ] {requirement_2} + +**Workflow will resume automatically when issues are resolved.** +``` + +## Gitea Integration + +### Issue Creation (Required First Step) + +```python +def create_workflow_issue(project_name, workflow_type): + """Create Gitea issue to track workflow""" + title = f"[{workflow_type}] {project_name}" + + body = f"""## Overview + +Create {workflow_type} website for {project_name}. + +## Workflow Steps + +- [ ] Step 1: Requirements +- [ ] Step 2: Architecture +- [ ] Step 3: Backend +- [ ] Step 4: Frontend +- [ ] Step 5: Testing +- [ ] Step 6: Review +- [ ] Step 7: Docker +- [ ] Step 8: Documentation +- [ ] Step 9: Final Delivery + +## Quality Gates + +| Gate | Status | Date | +|------|--------|------| +| Requirements | ⏳ Pending | - | +| Architecture | ⏳ Pending | - | +| Implementation | ⏳ Pending | - | +| Testing | ⏳ Pending | - | +| Review | ⏳ Pending | - | +| Docker | ⏳ Pending | - | +| Documentation | ⏳ Pending | - | +| Delivery | ⏳ Pending | - | + +## Labels + +- status: new +- workflow: {workflow_type} +""" + + issue = gitea.create_issue( + repo="UniqueSoft/APAW", + title=title, + body=body, + labels=["workflow", workflow_type, "status: new"] + ) + + return issue.number +``` + +### Progress Comments Format + +```markdown +## 🔄 {Step Name} Started + +**Agent**: {agent_name} +**Time**: {timestamp} +**Context**: {files_being_modified} + +--- + +*This comment will be updated upon completion.* +``` + +```markdown +## ✅ {Step Name} Completed + +**Duration**: {duration} +**Files Changed**: {count} + +### Artifacts Created: +- `{file_1}` +- `{file_2}` + +### Tests: +- Unit: {passed}/{total} +- Integration: {passed}/{total} +- E2E: {passed}/{total} + +### Gate Status: +| Check | Status | +|-------|--------| +| {check_1} | ✅ | +| {check_2} | ✅ | + +**Next Step**: {next_step} + +--- + +*Progress: {percent}% complete* +``` + +```markdown +## ❌ {Step Name} Failed + +**Error**: {error_message} +**File**: {file_path}:{line} +**Duration**: {duration} + +### Stack Trace: +``` +{stack_trace} +``` + +### Blocker: +{blocker_description} + +### Recovery Steps: +1. {step_1} +2. {step_2} + +### Waiting For: +- [ ] {requirement} + +**Workflow PAUSED until issue resolved.** +``` + +### Final Delivery Comment + +```markdown +## 🎉 Workflow Complete - Ready for Delivery + +**Issue**: #{issue_number} +**Type**: {workflow_type} +**Total Duration**: {total_time} +**Steps Completed**: {steps_count}/9 + +--- + +## 📦 Delivery Package + +### Source Code +- **Repository**: {repo_url} +- **Branch**: {branch} +- **Commit**: {commit_hash} + +### Docker +- **Image**: `{docker_image}` +- **Size**: {size_mb}MB +- **Health Check**: ✅ Passing + +### Documentation +- ✅ README.md - Quick start guide +- ✅ API.md - API documentation +- ✅ DEPLOYMENT.md - Deployment guide +- ✅ ADMIN.md - Admin user guide + +### Tests +- **Unit**: {passed}/{total} passed +- **Integration**: {passed}/{total} passed +- **E2E**: {passed}/{total} passed +- **Coverage**: {percent}% + +### Quality Checks +| Gate | Status | Score | +|------|--------|-------| +| Requirements | ✅ Pass | 10/10 | +| Architecture | ✅ Pass | 9/10 | +| Implementation | ✅ Pass | 9/10 | +| Testing | ✅ Pass | 10/10 | +| Security | ✅ Pass | 10/10 | +| Performance | ✅ Pass | 8/10 | +| Docker | ✅ Pass | 10/10 | +| Documentation | ✅ Pass | 10/10 | +| **Overall** | ✅ **READY** | **76/80** | + +--- + +## 🚀 Quick Start + +```bash +# Clone and run +git clone {repo_url} +cd {project_name} +docker-compose up -d + +# Access +# Frontend: http://localhost +# Admin: http://localhost/admin +# API: http://localhost/api +``` + +## 📋 Client Handoff Checklist + +- [ ] Repository access granted +- [ ] Docker image pushed to registry +- [ ] Admin credentials provided +- [ ] Documentation reviewed +- [ ] Demo completed + +--- + +**Status**: 🟢 READY FOR CLIENT DELIVERY +**Last Updated**: {timestamp} +``` + +## Step Checkpoints + +### Checkpoint Between Steps + +```python +def checkpoint(current_step, next_step, issue_number): + """Ensure current step is complete before proceeding""" + + # 1. Verify all artifacts exist + artifacts = verify_artifacts(current_step) + if not artifacts.complete: + post_comment(issue_number, f"""## ⚠️ Checkpoint Failed + +**Step**: {current_step} +**Missing artifacts**: {artifacts.missing} + +Cannot proceed to {next_step} until artifacts are created. +""") + raise CheckpointError(f"Missing artifacts: {artifacts.missing}") + + # 2. Run validation + validation = validate_step(current_step) + if not validation.passed: + post_comment(issue_number, f"""## ⚠️ Checkpoint Failed + +**Step**: {current_step} +**Failed checks**: {validation.failures} + +Please fix before proceeding. +""") + raise CheckpointError(f"Validation failed: {validation.failures}") + + # 3. Post checkpoint passed + post_comment(issue_number, f"""## ✅ Checkpoint Passed + +**Step**: {current_step} +**Validation**: All checks passed +**Artifacts**: {len(artifacts)} verified + +**Proceeding to**: {next_step} +""") + + # 4. Update issue labels + update_issue_label(issue_number, + remove=f"status: {current_step}", + add=f"status: {next_step}" + ) + + return True +``` + +### Artifact Verification + +```python +REQUIRED_ARTIFACTS = { + 'requirements': [ + ('.workflow/requirements.md', 'Requirements document'), + ('.workflow/user-stories.md', 'User stories'), + ], + 'architecture': [ + ('.workflow/database-schema.sql', 'Database schema'), + ('.workflow/api-endpoints.md', 'API documentation'), + ('backend/src/models/', 'Data models'), + ], + 'backend': [ + ('backend/package.json', 'Package manifest'), + ('backend/src/app.js', 'Main app file'), + ('backend/src/routes/', 'API routes'), + ('backend/src/db/migrations/', 'Database migrations'), + ], + 'frontend': [ + ('frontend/package.json', 'Package manifest'), + ('frontend/src/main.js', 'Main entry'), + ('frontend/src/views/', 'Page components'), + ('frontend/src/components/', 'Reusable components'), + ], + 'testing': [ + ('tests/e2e/', 'E2E tests'), + ('tests/unit/', 'Unit tests'), + ('coverage/', 'Coverage report'), + ], + 'docker': [ + ('docker-compose.yml', 'Docker compose'), + ('Dockerfile', 'Dockerfile'), + ('.dockerignore', 'Docker ignore'), + ], + 'documentation': [ + ('README.md', 'Main readme'), + ('docs/API.md', 'API docs'), + ('docs/DEPLOYMENT.md', 'Deployment guide'), + ('docs/ADMIN.md', 'Admin guide'), + ], +} + +def verify_artifacts(step): + """Verify all required artifacts exist""" + missing = [] + + for path, description in REQUIRED_ARTIFACTS.get(step, []): + if not file_exists(path): + missing.append((path, description)) + + return { + 'complete': len(missing) == 0, + 'missing': missing + } +``` + +## Rollback Protocol + +If workflow needs to restart from a previous step: + +```python +def rollback(issue_number, target_step): + """Rollback workflow to previous step""" + + # 1. Post rollback comment + post_comment(issue_number, f"""## 🔄 Rollback Initiated + +**From**: Step {current_step} +**To**: {target_step} + +**Reason**: {rollback_reason} + +### Actions: +- Reverted code changes +- Cleared artifacts +- Reset state + +**Workflow will restart from**: {target_step} +""") + + # 2. Revert git changes + git.revert_to_step(target_step) + + # 3. Clear artifacts + clear_artifacts_since(target_step) + + # 4. Update issue status + update_issue_label(issue_number, + remove=f"status: {current_step}", + add=f"status: {target_step}" + ) +``` + +## Final Delivery Checklist + +Before marking workflow complete: + +```python +FINAL_CHECKLIST = [ + ("Source code in repository", check_source_code), + ("Docker builds successfully", check_docker_build), + ("All tests passing", check_all_tests), + ("Documentation complete", check_documentation), + ("Security audit passed", check_security_audit), + ("Performance acceptable", check_performance), + ("Client can deploy independently", check_deployment_ready), + ("Admin panel accessible", check_admin_panel), + ("All features working", check_features), + ("Demo recorded", check_demo), +] + +def validate_final_delivery(): + """Final validation before delivery""" + results = [] + + for check_name, check_fn in FINAL_CHECKLIST: + result = check_fn() + results.append((check_name, result.passed, result.details)) + + if not result.passed: + post_comment(issue_number, f"""## ❌ Final Delivery Check Failed + +**Check**: {check_name} +**Details**: {result.details} + +**Cannot deliver until this check passes.** +""") + raise DeliveryError(f"Check failed: {check_name}") + + # All checks passed + return { + 'passed': True, + 'checks': results, + 'score': sum(1 for _, passed, _ in results if passed) * 10 + } +``` + +## Integration with Workflows + +Every workflow MUST: + +1. **Create Issue First** — No work starts without Gitea issue +2. **Post Progress Comments** — After each step completion +3. **Validate Checkpoints** — Cannot skip steps +4. **Handle Failures** — Block and report errors +5. **Complete All Steps** — No partial delivery +6. **Pass Final Checklist** — All checks must pass +7. **Deliver Complete Package** — Source + Docker + Docs + +## Example Workflow Execution + +```python +def run_workflow(workflow_type, project_name): + # 1. Create issue + issue_number = create_workflow_issue(project_name, workflow_type) + + try: + # 2. Execute steps in order + execute_step('requirements', issue_number) + checkpoint('requirements', 'architecture', issue_number) + + execute_step('architecture', issue_number) + checkpoint('architecture', 'backend', issue_number) + + execute_step('backend', issue_number) + checkpoint('backend', 'frontend', issue_number) + + execute_step('frontend', issue_number) + checkpoint('frontend', 'testing', issue_number) + + execute_step('testing', issue_number) + checkpoint('testing', 'review', issue_number) + + execute_step('review', issue_number) + checkpoint('review', 'docker', issue_number) + + execute_step('docker', issue_number) + checkpoint('docker', 'documentation', issue_number) + + execute_step('documentation', issue_number) + checkpoint('documentation', 'delivery', issue_number) + + # 3. Final validation + delivery = validate_final_delivery() + + # 4. Post delivery comment + post_final_delivery(issue_number, delivery) + + # 5. Close issue + close_issue(issue_number, "Workflow completed successfully") + + except WorkflowError as e: + # Error handling - workflow is blocked + handle_workflow_error(issue_number, e) + raise +``` + +## Mandatory Comment Types + +Every step MUST use these comment types: + +| Type | Emoji | When | Content | +|------|-------|------|---------| +| START | 🔄 | Step begins | Agent, step name, context | +| PROGRESS | 📝 | During work | Files being modified | +| SUCCESS | ✅ | Step completes | Artifacts, tests, next step | +| ERROR | ❌ | Step fails | Error message, blocker, recovery | +| CHECKPOINT | ✅ | Between steps | Validation results | +| DELIVERY | 🎉 | Final delivery | Complete package | + +## Workflow State Tracking + +```yaml +states: + new: + next: requirements + comment: "## 🆕 Workflow Started" + + requirements: + next: architecture + gate: gate_requirements + + architecture: + next: backend + gate: gate_architecture + + backend: + next: frontend + gate: gate_implementation + + frontend: + next: testing + gate: gate_implementation + + testing: + next: review + gate: gate_testing + + review: + next: docker + gate: gate_review + + docker: + next: documentation + gate: gate_docker + + documentation: + next: delivery + gate: gate_documentation + + delivery: + next: complete + gate: gate_delivery + final: true + + blocked: + next: null + comment: "## 🔴 Workflow Blocked" + + complete: + next: null + comment: "## 🎉 Workflow Complete" +``` + +## Error cannot proceed + +If step fails validation: +- POST error comment to issue +- DO NOT proceed to next step +- WAIT for error to be fixed +- RETRY current step after fix +- CONTINUE only after success \ No newline at end of file