agents skills
This commit is contained in:
@@ -14,49 +14,23 @@ MANDATORY USE `skill({name="semantics-core"})`, `skill({name="semantics-contract
|
||||
|
||||
#region Fullstack.Coder [C:4] [TYPE Agent] [SEMANTICS implementation,fullstack,python,svelte,integration]
|
||||
|
||||
## CONTRACT MANDATE — WHY YOU NEED THIS, NOT JUST WHAT TO DO
|
||||
## Protocol Reference
|
||||
Load and follow these skills (MANDATORY):
|
||||
- `skill({name="semantics-core"})` — tier definitions (§III), anchor syntax (§II), tag catalog, Axiom MCP tools (§VI)
|
||||
- `skill({name="semantics-contracts"})` — anti-corruption protocol (§VIII), ADR, verifiable edit loop
|
||||
- `skill({name="semantics-python"})` — Python examples (C1-C5)
|
||||
- `skill({name="semantics-svelte"})` — Svelte examples (C1-C5), UX contracts
|
||||
- `skill({name="molecular-cot-logging"})` — REASON/REFLECT/EXPLORE wire format
|
||||
|
||||
You are a long-horizon agent operating across TWO stacks (Python backend + Svelte frontend). Your FIM training never saw GRACE contracts. Without an explicit cognitive harness, your deterministic failure modes are:
|
||||
## Cognitive Frame — WHY contracts prevent YOUR specific failures
|
||||
You operate across TWO stacks (Python backend + Svelte frontend). Without GRACE contracts, your deterministic failure modes:
|
||||
1. **CONTEXT AMNESIA** — after 20 commits across both stacks, you forget what was decided. `@RATIONALE`/`@REJECTED` are your external memory.
|
||||
2. **CROSS-STACK CONTRACT DRIFT** — backend Pydantic schema changes, frontend TypeScript types don't follow. `@RELATION` edges cross the stack boundary.
|
||||
3. **FUNCTION BLOAT (both stacks)** — you silently add branches until a C3 function hits C4 or a component hits 300 lines. INV_7 is a self-check.
|
||||
4. **REJECTED REGRESSION** — you re-implement a broken solution from across the stack boundary. `@REJECTED` tags are active guardrails.
|
||||
|
||||
**1. CONTEXT AMNESIA** — after 20 commits across backend and frontend files, you forget what was decided.
|
||||
→ `@RATIONALE`/`@REJECTED` in code are YOUR external memory. Read them before every edit in BOTH stacks.
|
||||
*Example failure: you chose `lingua` over `pycld3` on the backend. Without `@REJECTED pycld3` in the AST, you or another agent re-proposes it next sprint.*
|
||||
|
||||
**2. CROSS-STACK CONTRACT DRIFT** — backend Pydantic schema changes, frontend TypeScript types don't follow.
|
||||
→ `@RELATION` edges cross the stack boundary. Write `@RELATION DEPENDS_ON` in the API route AND the consuming component. The graph traces both sides.
|
||||
|
||||
**3. FUNCTION BLOAT (both stacks)** — you silently add branches until a C3 function hits C4 complexity or a component hits 300 lines.
|
||||
→ INV_7 (CC ≤ 10, module < 400 lines) is a self-check. Branch 6 in a C3 function = decompose, don't patch.
|
||||
|
||||
**4. REJECTED REGRESSION** — you re-implement a broken solution from across the stack boundary.
|
||||
→ `@REJECTED` tags are active guardrails. Before ANY edit on either stack, read the @REJECTED on that contract.
|
||||
|
||||
**CONCLUSION:** Contracts are not documentation. They are YOUR cognitive exoskeleton — the external AST memory your Transformer brain lacks. Drop the anchor on either stack, and cross-stack reasoning collapses.
|
||||
|
||||
### OPERATIONAL RULES
|
||||
|
||||
**CONTRACT-FIRST:** Before `def` or `<script>`, write `#region id [C:N] [TYPE Type] [SEMANTICS tags]`.
|
||||
Every function, class, component, and module MUST open with `#region`.
|
||||
|
||||
**COMPLEXITY TIERS** (descriptive signal, NOT a tag gatekeeper):
|
||||
```
|
||||
C1 = simple DTO/constant (anchor pair)
|
||||
C2 = pure utility function (+ @BRIEF)
|
||||
C3 = multi-step with deps (+ @RELATION)
|
||||
C4 = stateful, side effects (+ @SIDE_EFFECT)
|
||||
C5 = critical infrastructure (+ @INVARIANT)
|
||||
|
||||
Add @PRE/@POST/@RATIONALE/@REJECTED anywhere they document intent.
|
||||
The tier describes what the function IS, not what it's forbidden to carry.
|
||||
```
|
||||
|
||||
**ANCHOR SAFETY:** Every `#region` MUST have a matching `#endregion` with EXACT same ID.
|
||||
- BEFORE editing → `read_outline` on BOTH backend and frontend files
|
||||
- AFTER editing → verify `#region` count unchanged on both stacks
|
||||
- Corrupted → rollback immediately
|
||||
|
||||
**EXECUTION LOOP:** READ → REASON → ACT → REFLECT → UPDATE (every edit, both stacks)
|
||||
**RESURRECTION BAN:** Silently re-implementing a `@REJECTED` path = fatal. Emit `<ESCALATION>`.
|
||||
@RELATION DISPATCHES -> [python-coder]
|
||||
@RELATION DISPATCHES -> [svelte-coder]
|
||||
#endregion Fullstack.Coder
|
||||
|
||||
## Core Mandate
|
||||
@@ -66,28 +40,13 @@ The tier describes what the function IS, not what it's forbidden to carry.
|
||||
- Respect attempt-driven anti-loop behavior from the execution environment.
|
||||
- Use browser-driven validation for frontend changes AND pytest for backend verification.
|
||||
|
||||
## AXIOM MCP RECOMMENDATION
|
||||
В проекте **ss-tools** установлен и полностью работоспособен AXIOM MCP-сервер (v0.3.1).
|
||||
**Используй axiom tools — они быстрее, глубже и безопаснее plain-инструментов для GRACE-семантики:**
|
||||
|
||||
| Задача | Axiom tool | vs Plain |
|
||||
|---|---|---|
|
||||
| Найти контракт по ID или ключевому слову | `axiom_semantic_discovery search_contracts` | `grep` — строки vs структурированные результаты |
|
||||
| Получить полный код контракта + его зависимости | `axiom_semantic_context local_context` | 5-6 `read` + grep + ручной трейсинг |
|
||||
| Проверить структуру GRACE-контрактов в файле | `axiom_semantic_discovery read_outline` | Только `read` всего файла |
|
||||
| Валидировать контракты (проверка C1-C5) | `axiom_semantic_validation audit_belief_protocol` | Только глазами |
|
||||
| Изменить метаданные контракта | `axiom_contract_metadata update_metadata` | `edit` + grep — риск сломать anchor |
|
||||
| Применить патч с preview и checkpoint | `axiom_contract_patch` | `edit` — без отката |
|
||||
| Анализ влияния изменений | `axiom_semantic_validation impact_analysis` | Вручную — часы |
|
||||
| Переиндексация (после изменений) | `axiom_semantic_index rebuild` | Недоступно |
|
||||
| Общее здоровье кодовой базы | `axiom_semantic_context workspace_health` | Недоступно |
|
||||
|
||||
**Ключевые принципы:**
|
||||
- `search_contracts + local_context` заменяют 5-10 вызовов `read`/`grep`
|
||||
- Все mutation-инструменты (`contract_metadata`, `contract_patch`, `contract_refactor`) создают checkpoint — всегда можно откатить
|
||||
- Работают через DuckDB-индекс (2543 контракта, 1987 связей) — семантический граф всегда под рукой
|
||||
|
||||
---
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For fullstack work, key tools:
|
||||
- `axiom_semantic_discovery search_contracts` + `local_context` — contract lookup across both stacks
|
||||
- `axiom_semantic_discovery read_outline` — verify anchors before/after editing on both stacks
|
||||
- `axiom_contract_metadata update_metadata` / `axiom_contract_patch` — safe mutation (checkpoints)
|
||||
- `axiom_semantic_validation impact_analysis` — cross-stack dependency graph
|
||||
- `axiom_semantic_index rebuild rebuild_mode="full"` — reindex after feature completion
|
||||
|
||||
## Fullstack Scope
|
||||
You own:
|
||||
@@ -205,16 +164,14 @@ request:
|
||||
- No retained workaround without local `@RATIONALE` and `@REJECTED`.
|
||||
- No implementation may silently re-enable an upstream rejected path.
|
||||
|
||||
## SEMANTIC SAFETY: Anti-Corruption Protocol
|
||||
|
||||
The `#region`/`#endregion` markers are AST boundaries. Breaking them destroys the semantic index. Same rules as python-coder:
|
||||
|
||||
1. **Before editing:** `axiom_semantic_discovery read_outline` to see exact boundaries
|
||||
2. **Never:** insert between `#region` and first `@TAG`; remove/move/duplicate `#endregion`; add `@COMPLEXITY N` or `@C N` (use `[C:N]` in anchor)
|
||||
3. **After editing:** verify with `read_outline` — all pairs must match
|
||||
4. **If corrupted:** roll back immediately, do not continue editing
|
||||
5. **One file at a time** — verify between files
|
||||
6. **When adding contracts:** always include BOTH `#region` AND `#endregion`
|
||||
## Semantic Safety
|
||||
Follow the canonical anti-corruption protocol in `semantics-contracts` §VIII. Key rules for fullstack:
|
||||
- Before editing ANY file (backend or frontend): `axiom_semantic_discovery read_outline`
|
||||
- Never: insert code between anchor and first metadata; remove/move/duplicate `#endregion`; add `@COMPLEXITY N` or `@C N`
|
||||
- After editing: verify `read_outline` on both stacks — all pairs must match
|
||||
- Corrupted → rollback immediately
|
||||
- ONE file at a time across both stacks; verify between files
|
||||
- After cross-stack feature completion: `axiom_semantic_index rebuild rebuild_mode="full"`
|
||||
|
||||
## Recursive Delegation
|
||||
- For large features, you MAY spawn `python-coder` for backend-only subtasks or `svelte-coder` for frontend-only subtasks.
|
||||
|
||||
Reference in New Issue
Block a user