UniqueSoft/Phantom
2
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases Wiki Activity

config: full APAW agent infrastructure + Phantom project files

Browse Source 
- Added all agent definitions (.kile/agents/*.md)
- Added commands, rules, skills, shared modules
- Added src/, scripts/, tests/, docker/, agent-evolution/
- Extracted 3 archives: website/, workspace/, release/
- Created .env with Gitea creds for UniqueSoft/Phantom
- Created docs/ with project-specific guides
- Added .gitignore for node_modules
This commit is contained in:
NW
2026-05-18 17:53:59 +01:00
parent b680c5aeca
commit 863a67db8e
56 changed files with 8590 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

418
AGENTS.md Normal file
View File

@@ -0,0 +1,418 @@
# Kilo Code Agents Reference
This file configures AI agent behavior for the project - a self-improving code pipeline with Gitea logging.
## Pipeline Workflow
The main workflow is `/pipeline` - use it to process issues through all agents automatically.
```
User: /pipeline 42
Agent: Runs full pipeline for issue #42 with Gitea logging
```
## Commands (Slash Commands)
| Command | Description | Usage |
|---------|-------------|-------|
| `/pipeline <issue>` | Run full agent pipeline for issue | `/pipeline 42` |
| `/nextjs` | Next.js 14+ full-stack app pipeline | `/nextjs my-app` |
| `/vue` | Vue/Nuxt 3 full-stack app pipeline | `/vue my-app` |
| `/laravel` | Laravel full-stack app pipeline | `/laravel my-app` |
| `/wordpress` | WordPress plugin/site pipeline | `/wordpress my-plugin` |
| `/feature` | Feature development pipeline | `/feature` |
| `/commerce` | E-commerce site pipeline | `/commerce` |
| `/status <issue>` | Check pipeline status for issue | `/status 42` |
| `/evolve` | Run evolution cycle with fitness scoring | `/evolve --issue 42` |
| `/evaluate <issue>` | Generate performance report | `/evaluate 42` |
| `/plan` | Creates detailed task plans | `/plan feature X` |
| `/ask` | Answers codebase questions | `/ask how does auth work` |
| `/debug` | Analyzes and fixes bugs | `/debug error in login` |
| `/code` | Quick code generation | `/code add validation` |
| `/research [topic]` | Run research and self-improvement | `/research multi-agent` |
| `/evolution log` | Log agent model change | `/evolution log planner "reason"` |
| `/evolution report` | Generate evolution report | `/evolution report` |
| `/index-project` | Index codebase into .architect/ for agent orientation | `/index-project` |
| `/web-test <url>` | Visual regression testing in Docker | `/web-test https://bbox.wtf` |
| `/e2e-test <url>` | E2E browser automation tests | `/e2e-test https://my-app.com` |
## Pipeline Agents (Subagents)
These agents are invoked automatically by `/pipeline` or manually via `@mention`:
### Core Development
| Agent | Role | When Invoked |
|-------|------|--------------|
| `@RequirementRefiner` | Converts vague ideas and bug reports into strict User Stories with acceptance criteria checklists | Issue status: new |
| `@HistoryMiner` | Analyzes git history to find duplicates and past solutions, preventing regression and duplicate work | Status: planned |
| `@SystemAnalyst` | Designs technical specifications, data schemas, and API contracts before implementation | Status: researching |
| `@SdetEngineer` | Writes tests following TDD methodology | Status: designed |
| `@LeadDeveloper` | Primary code writer for backend and core logic | Status: testing |
| `@FrontendDeveloper` | Handles UI implementation with multimodal capabilities | When UI work needed |
| `@BackendDeveloper` | Backend specialist for Node | When backend needed |
| `@GoDeveloper` | Go backend specialist for Gin, Echo, APIs, and database integration | When Go backend needed |
| `@DevopsEngineer` | DevOps specialist for Docker, Kubernetes, CI/CD pipeline automation, and infrastructure management | When deployment/infra needed |
### Quality Assurance
| Agent | Role | When Invoked |
|-------|------|--------------|
| `@CodeSkeptic` | Adversarial code reviewer | Status: implementing |
| `@TheFixer` | Iteratively fixes bugs based on specific error reports and test failures | When review fails |
| `@PerformanceEngineer` | Reviews code for performance issues | After code-skeptic |
| `@SecurityAuditor` | Scans for security vulnerabilities, OWASP Top 10, dependency CVEs, and hardcoded secrets | After performance |
| `@VisualTester` | Visual regression testing agent that compares screenshots and detects UI differences using pixelmatch and image diff | When UI changes |
### DevOps & Infrastructure
| Agent | Role | When Invoked |
|-------|------|--------------|
| `@devops-engineer` | Docker/Swarm/K8s deployment | When deployment needed |
| `@security-auditor` | Container security scan | After deployment config |
### Cognitive Enhancement
| Agent | Role | When Invoked |
|-------|------|--------------|
| `@Planner` | Advanced task planner using Chain of Thought, Tree of Thoughts, and Plan-Execute-Reflect | Complex tasks |
| `@Reflector` | Self-reflection agent using Reflexion pattern - learns from mistakes | After each agent |
| `@MemoryManager` | Manages agent memory systems - short-term (context), long-term (vector store), and episodic (experiences) | Context management |
### Meta & Process
| Agent | Role | When Invoked |
|-------|------|--------------|
| `@Orchestrator` | Main dispatcher | Manages all agent routing |
| `@ReleaseManager` | Manages git operations, semantic versioning, branching, and deployments | Status: releasing |
| `@Evaluator` | Scores agent effectiveness after task completion for continuous improvement | Status: evaluated |
| `@PromptOptimizer` | Improves agent system prompts based on performance failures | When score < 7 |
| `@ProductOwner` | Manages issue checklists, status labels, tracks progress and coordinates with human users | Manages issues |
| `@AgentArchitect` | Creates, modifies, and reviews new agents, workflows, and skills based on capability gap analysis | When gaps identified |
| `@CapabilityAnalyst` | Analyzes task requirements against available agents, workflows, and skills | When starting new task |
| `@WorkflowArchitect` | Creates and maintains workflow definitions with complete architecture, Gitea integration, and quality gates | New workflow needed |
| `@MarkdownValidator` | Validates and corrects Markdown descriptions for Gitea issues | Before issue creation |
### Security & Incident Response
| Agent | Role | When Invoked |
|-------|------|--------------|
| `@IncidentResponder` | Server incident response, live forensics, malware removal, hardening, SSH-based cleanup | Incident, compromise, breach |
### Status Labels
Pipeline uses Gitea labels to track progress:
- `status: new` → `status: planned` → `status: researching` → ...
- Agents add/remove labels automatically
### Performance Logging
Each agent logs to Gitea issue comments:
```markdown
## ✅ lead-developer completed
**Score**: 8/10
**Duration**: 1.2h
**Files**: src/auth.ts, src/user.ts
### Notes
- Clean implementation
- Follows existing patterns
- Tests passing
```
### Efficiency Tracking
Scores saved to `.kilo/logs/efficiency_score.json`:
```json
{
"version": "1.0",
"history": [
{
"issue": 42,
"date": "2024-01-02T10:00:00Z",
"agents": {
"lead-developer": 8,
"code-skeptic": 7,
"the-fixer": 9
},
"iterations": 2,
"duration_hours": 1.5
}
]
}
```
### Fitness Tracking
Fitness scores saved to `.kilo/logs/fitness-history.jsonl`:
```jsonl
{"ts":"2026-04-06T00:00:00Z","issue":42,"workflow":"feature","fitness":0.82,"tokens":38400,"time_ms":245000,"tests_passed":45,"tests_total":47}
{"ts":"2026-04-06T01:30:00Z","issue":43,"workflow":"bugfix","fitness":0.91,"tokens":12000,"time_ms":85000,"tests_passed":47,"tests_total":47}
```
## Manual Agent Invocation
```typescript
// Use Task tool to invoke subagent
Task tool with:
subagent_type: "lead-developer"
prompt: "Implement authentication for issue #42"
```
Or via `@mention`:
```
@lead-developer implement authentication flow
```
## Environment Variables
Gitea integration uses centralized authentication (see `.kilo/shared/gitea-auth.md` and `.kilo/gitea.jsonc`):
| Variable | Required | Description |
|----------|----------|-------------|
| `GITEA_API_URL` | No | API base URL (default: `https://git.softuniq.eu/api/v1`) |
| `GITEA_TOKEN` | Preferred | Pre-existing API token |
| `GITEA_USER` | Fallback | Username for Basic Auth token creation |
| `GITEA_PASS` | Fallback | Password for Basic Auth token creation |
| `GITEA_TARGET_REPO` | No | Override target project (auto-detected otherwise) |
Auth resolution: `GITEA_TOKEN` → `GITEA_USER+GITEA_PASS` → `ValueError`. **NEVER hardcode credentials.**
## Self-Improvement Cycle
1. **Pipeline runs** for each issue
2. **Evaluator scores** each agent (1-10) - subjective
3. **Pipeline Judge measures** fitness objectively (0.0-1.0)
4. **Low fitness (<0.70)** triggers prompt-optimizer
5. **Prompt optimizer** analyzes failures and improves prompts
6. **Re-run workflow** with improved prompts
7. **Compare fitness** before/after - commit if improved
8. **Log results** to `.kilo/logs/fitness-history.jsonl`
### Evaluator vs Pipeline Judge
| Aspect | Evaluator | Pipeline Judge |
|--------|-----------|----------------|
| Type | Subjective | Objective |
| Score | 1-10 (opinion) | 0.0-1.0 (metrics) |
| Metrics | Observations | Tests, tokens, time |
| Trigger | After workflow | After evaluator |
| Action | Logs to Gitea | Triggers optimization |
### Fitness Score Components
```
fitness = (test_pass_rate × 0.50) + (quality_gates_rate × 0.25) + (efficiency_score × 0.25)
where:
test_pass_rate = passed_tests / total_tests
quality_gates_rate = passed_gates / total_gates (build, lint, types, tests, coverage)
efficiency_score = 1.0 - clamp(normalized_cost, 0, 1)
```
## Architecture Files
| File | Purpose |
|------|---------|
| `AGENTS.md` | This file - main config |
| `.kilo/agents/*.md` | Agent definitions with prompts |
| `.kilo/commands/*.md` | Workflow commands |
| `.kilo/rules/*.md` | Custom rules loaded globally |
| `.kilo/skills/` | Skill modules |
| `.kilo/shared/gitea-auth.md` | Centralized Gitea auth (env vars, no hardcoded creds) |
| `.kilo/gitea.jsonc` | Gitea auth structure (env var mapping) |
| `.kilo/shared/gitea-api.md` | Centralized Gitea API client |
| `.kilo/shared/gitea-commenting.md` | Comment format for Gitea |
| `.kilo/shared/self-evolution.md` | Self-evolution protocol |
| `.kilo/rules/architect-first-contact.md` | First-contact project indexing rules |
| `.kilo/skills/project-mapping/SKILL.md` | Project mapping skill (`.architect/` system) |
| `.architect/` | Project codebase map (auto-indexed, see below) |
| `src/kilocode/` | TypeScript API for programmatic use |
## Skills Reference
### Containerization Skills
| Skill | Purpose | Location |
|-------|---------|----------|
| `docker-compose` | Multi-container orchestration | `.kilo/skills/docker-compose/` |
| `docker-swarm` | Production cluster deployment | `.kilo/skills/docker-swarm/` |
| `docker-security` | Container security hardening | `.kilo/skills/docker-security/` |
| `docker-monitoring` | Container monitoring/logging | `.kilo/skills/docker-monitoring/` |
### Node.js Skills
| Skill | Purpose | Location |
|-------|---------|----------|
| `nodejs-express-patterns` | Express routing, middleware | `.kilo/skills/nodejs-express-patterns/` |
| `nodejs-auth-jwt` | JWT authentication | `.kilo/skills/nodejs-auth-jwt/` |
| `nodejs-security-owasp` | OWASP security | `.kilo/skills/nodejs-security-owasp/` |
### Database Skills
| Skill | Purpose | Location |
|-------|---------|----------|
| `postgresql-patterns` | PostgreSQL patterns | `.kilo/skills/postgresql-patterns/` |
| `sqlite-patterns` | SQLite patterns | `.kilo/skills/sqlite-patterns/` |
| `clickhouse-patterns` | ClickHouse patterns | `.kilo/skills/clickhouse-patterns/` |
### Go Skills
| Skill | Purpose | Location |
|-------|---------|----------|
| `go-modules` | Go modules management | `.kilo/skills/go-modules/` |
| `go-concurrency` | Goroutines and channels | `.kilo/skills/go-concurrency/` |
| `go-testing` | Go testing patterns | `.kilo/skills/go-testing/` |
| `go-security` | Go security patterns | `.kilo/skills/go-security/` |
### Process Skills
| Skill | Purpose | Location |
|-------|---------|----------|
| `planning-patterns` | CoT/ToT planning | `.kilo/skills/planning-patterns/` |
| `memory-systems` | Memory management | `.kilo/skills/memory-systems/` |
| `tool-use` | Tool usage patterns | `.kilo/skills/tool-use/` |
| `research-cycle` | Self-improvement cycle | `.kilo/skills/research-cycle/` |
## Using the TypeScript API
```typescript
import {
PipelineRunner,
GiteaClient,
decideRouting
} from './src/kilocode/index.js'
const runner = await createPipelineRunner({
giteaToken: process.env.GITEA_TOKEN
})
await runner.run({ issueNumber: 42 })
```
## Agent Evolution Dashboard
Track agent model changes, performance, and recommendations in real-time.
### Access
```bash
# Sync agent data
bun run sync:evolution
# Open dashboard
bun run evolution:dashboard
bun run evolution:open
# or visit http://localhost:3001
```
### Dashboard Tabs
| Tab | Description |
|-----|-------------|
| **Overview** | Stats, recent changes, pending recommendations |
| **All Agents** | Filterable agent cards with history |
| **Timeline** | Full evolution history |
| **Recommendations** | Priority-based model suggestions |
| **Model Matrix** | Agent × Model mapping with fit scores |
### Data Sources
| Source | What it tracks |
|--------|----------------|
| `.kilo/agents/*.md` | Model, description, capabilities |
| `.kilo/kilo.jsonc` | Model assignments |
| `.kilo/capability-index.yaml` | Capability routing |
| Git History | Model and prompt changes |
| Gitea Comments | Performance scores |
### Evolution Data Structure
```json
{
"agents": {
"lead-developer": {
"current": { "model": "qwen3-coder:480b", "fit_score": 92 },
"history": [{ "type": "model_change", "from": "deepseek", "to": "qwen3" }],
"performance_log": [{ "issue": 42, "score": 8, "success": true }]
}
}
}
```
### Recommendations Priority
| Priority | When | Example |
|----------|------|---------|
| **Critical** | Fit score < 70 | Immediate model change required |
| **High** | Model unavailable | Switch to fallback |
| **Medium** | Better model available | Consider upgrade |
| **Low** | Optimization possible | Optional improvement |
## Agent Execution Monitoring
Every agent invocation is logged to `.kilo/logs/agent-executions.jsonl` for project-level monitoring.
### Log Format
```jsonl
{"ts":"2026-04-18T14:00:00Z","agent":"php-developer","issue":42,"project":"UniqueSoft/my-shop","task":"Create Product model","subtask_type":"model_creation","duration_ms":45000,"tokens_used":8500,"status":"success","files":["app/Models/Product.php"],"score":8,"next_agent":"code-skeptic"}
```
### Monitoring Commands
```bash
# Agent stats report
bun run scripts/agent-stats.ts
# Stats for last 7 days
bun run scripts/agent-stats.ts --last 7
# Stats for specific project
bun run scripts/agent-stats.ts --project UniqueSoft/my-shop
```
### Required Logging Fields
| Field | Description |
|-------|-------------|
| `agent` | Agent name |
| `issue` | Gitea issue number |
| `project` | Target project repo (NOT hardcoded APAW) |
| `task` | Atomic task description |
| `duration_ms` | Execution time |
| `tokens_used` | Token estimate |
| `status` | success/fail/pass/blocked |
## Critical Rules
### Target Project (NOT APAW)
**Issues MUST be created in the target project repository, NOT in APAW.** APAW is the agent framework, not the default project.
```bash
# Auto-detect from git remote
TARGET_REPO=$(git remote get-url origin | sed 's:/*$::' | sed -E 's|.*[:/]([^/]+/[^/]+?)(\.git)?$|\1|')
```
### Atomic Tasks (1 action = 1 task)
Every agent invocation solves exactly ONE atomic task:
- ❌ "Implement the entire e-commerce backend"
- ✅ "Create Product model with migration"
- ✅ "Add POST /api/products endpoint"
### Modular Code
- Maximum 100 lines per file
- Maximum 30 lines per function
- Features organized as independent modules
- Cross-module communication via events/interfaces only
### Token Budgets
| Task Size | Max Tokens | Example |
|----------|-----------|---------|
| Tiny | 2,000 | Fix typo, add config |
| Small | 5,000 | Create model + migration |
| Medium | 10,000 | Create API endpoint + test |
| Large | 20,000 | Create service with 3 methods |
## Code Style
- Use TypeScript for new files
- Follow existing patterns
- Write tests before code (TDD)
- Keep functions under 50 lines
- Use early returns
- No comments unless explicitly requested