reactive-feature-dev · diff
git:20260603.a12f37b to git:20261103.92630ca
29 added, 148 removed. Audit A to A.
---
name: reactive-feature-dev
description: Complete feature development workflow for Reactive Agents. Orchestrates the correct sequence of skills for any feature type. Use at the start of any non-trivial implementation task to route to the right skills and follow the right order.
user-invocable: false
---
# Reactive Agents Feature Development Workflow
- ## Step 0: Route to the Right Skills First
-
- Before writing any code, identify what kind of work this is and load the corresponding skill:
-
- ```
- Is this kernel work (new phase, guard, meta-tool, custom kernel)?
- → Load: kernel-extension skill
-
- Is this provider or adapter work (new provider, streaming, adapter hooks)?
- → Load: provider-streaming skill
-
- Is this MCP work (docker-based tools, transport, container lifecycle)?
- → Load: mcp-integration skill
-
- Is this a new service in an existing package?
- → Load: implement-service skill
+ ## Step 0: Route to the right skills
- Is this a new package?
- → Load: build-package skill (add-new-package)
- ```
+ | Work | Load |
+ |---|---|
+ | Kernel (phase, guard, meta-tool, custom kernel) | `kernel-extension` |
+ | Provider / adapter / streaming | `provider-streaming` |
+ | MCP (docker tools, transport, container lifecycle) | `mcp-integration` |
+ | New service in an existing package | `implement-service` |
+ | New package | `build-package` |
- For all cases, also load: `agent-tdd` (write tests first), `effect-ts-patterns` (required for all code).
+ Always also: `agent-tdd` (tests first), `effect-ts-patterns` (all code), `repo-tool` (commands below).
- ## Step 1: Read Before Writing
+ ## Step 1: Orient
```bash
- # 1. Confirm current architecture
- cat AGENTS.md | head -100
-
- # 2. Read the affected package's source entry point
- # (see architecture-reference skill for the right first file per package)
-
- # 3. Identify which dependency layers are affected
- # Changes to upstream packages (core, llm-provider) require downstream rebuild
- ```
-
- Do NOT skip this step. Writing code without reading the affected package first causes:
-
- - Duplicate implementations of existing functionality
- - Wrong dependency layer — editing a higher-layer package when the change belongs in a lower one
- - Breaking existing patterns because you didn't see them
-
- ## Step 2: Identify Dependency Impact
-
- Check the build order before touching any package:
-
- ```
- Layer 0: core → llm-provider (changes here require rebuilding EVERYTHING downstream)
- Layer 1: memory, tools, guardrails, cost, identity, observability, interaction, prompts, eval, a2a
- Layer 2: reasoning, verification, orchestration, gateway, reactive-intelligence
- Layer 3: runtime → reactive-agents (facade)
- ```
-
- If your change touches Layer 0 or 1, plan for cross-package type verification.
-
- ## Step 3: Write the Failing Test First (agent-tdd)
-
- Following `agent-tdd` skill:
-
- ```typescript
- // 1. Create test file with mandatory header
- // Run: bun test packages/<pkg>/tests/<your-file>.test.ts --timeout 15000
-
- // 2. Write ONE failing test that captures the desired behavior
- // 3. Run it — confirm it fails with the right error
- bun test packages/<pkg>/tests/<your-file>.test.ts --timeout 15000
-
- // 4. Write minimal code to pass
- // 5. Run again — confirm it passes
- // 6. Add edge case tests, refactor
+ bun run repo status # branch, plans, debt
+ bun run repo scope <files you will touch> # owner/warden, checks, docs
+ bun run repo find "<symbol or topic>" # then: bun run repo outline <file>, Read a range
```
- ## Step 4: Implement with Effect-TS Patterns
-
- Following `effect-ts-patterns` skill:
-
- - All data shapes: `Schema.Struct` — never `interface` or `type { ... }`
- - All errors: `Data.TaggedError` — never `throw new Error()`
- - All state: `Ref.make` / `Ref.get` / `Ref.update` — never `let`
- - All async: `Effect.tryPromise` — never `await`
- - All imports: `.js` extension on relative imports (Bun ESM)
- - All service methods: `readonly` keyword
+ Read the affected package's entry point first (`architecture-reference` names it) and its upstream layers. Changes to `core` / `llm-provider` need downstream rebuild and type verification. Domain-scoped edits go through the owning warden (AGENTS.md ownership table).
- ## Step 5: Validate Before Committing
+ ## Step 2: Failing test first (`agent-tdd`)
- Run both validators:
+ Write ONE failing test, run it, confirm the right failure, write minimal code, rerun, then edge cases:
```bash
- # 1. Pattern compliance (anti-pattern grep)
- # (from validate-build skill)
- grep -rn "throw new" packages/<pkg>/src/ || echo "✅ No throw"
- grep -rn "^interface " packages/<pkg>/src/ || echo "✅ No plain interfaces"
- grep -rn "let " packages/<pkg>/src/ || echo "✅ No let"
- grep -rn "await " packages/<pkg>/src/ || echo "✅ No raw await"
-
- # 2. Full package test
- bun test packages/<pkg> --timeout 15000
-
- # 3. Typecheck
- bun run typecheck --filter @reactive-agents/<pkg>
-
- # 4. Build (if touching a built package)
- bun run build --filter @reactive-agents/<pkg>
+ bun run repo test packages/<pkg>/tests/<file>.test.ts
```
- For kernel changes, also run `review-patterns` Category 9 (kernel-extension compliance).
-
- ## Step 6: Update Documentation
-
- Following `update-docs` skill:
-
- ```bash
- # Check what changed
- git diff --name-only HEAD
+ ## Step 3: Implement (`effect-ts-patterns`)
- # Update AGENTS.md if: new package, new builder method, test count changed
- # Update README.md if: new package, new provider, new capability
- # Update docs site if: new feature needs a docs page
- # Update .agents/MEMORY.md with new capabilities/patterns
- ```
+ `Schema.Struct` for data, `Data.TaggedError` for errors, `Ref` for state, `Effect.tryPromise` for async, `.js` on relative imports, `readonly` service methods. No `any`.
- ## Step 7: Commit and Add Changeset
+ ## Step 4: Validate
```bash
- # Stage specific files — never git add -A
- git add packages/<pkg>/src/ packages/<pkg>/tests/
-
- # Commit with present-tense description of what changed
- git commit -m "feat(<pkg>): <what the change does>"
-
- # Add changeset for version bump
- bun run changeset
- # Choose: patch (bug fix), minor (new feature), major (breaking change)
+ bun run repo verify packages/<pkg> # tests + typecheck + narrow gates
+ bun run repo check --all # repo gates
```
- ## Dead Code Areas — Do Not Touch
-
- These sections exist in the codebase but are disabled. Do not modify, re-enable, or "clean up":
-
- | Area | Location | Size |
- |------|---------|------|
- | `buildDynamicContext` | `packages/reasoning/src/context/context-engine.ts` | ~280 LOC |
- | `buildStaticContext` | same file (LIVE — active static prompt builder) | ~280 LOC |
- | Dead text-assembly functions | `packages/reasoning/src/kernel/capabilities/attend/context-utils.ts` | ~690 LOC total |
-
- These are preserved as reference. Any PR that modifies them will be rejected.
-
- ## Quality Gates Before Any Commit
-
- All of these must pass. No exceptions:
+ Pattern review (`review-patterns`); kernel changes also its Category 9. Build when touching a built package (`packages/reasoning` exports `dist`: rebuild before downstream tests).
- - [ ] No `any` types (including `as any` casts)
- - [ ] No `interface` for data shapes (use `Schema.Struct`)
- - [ ] No `let` for mutable state (use `Ref`)
- - [ ] No `await` (use `Effect.tryPromise` or `Effect.sync`)
- - [ ] No `throw` (use `Data.TaggedError`)
- - [ ] All relative imports have `.js` extension
- - [ ] All tests pass: `bun test packages/<pkg> --timeout 15000`
- - [ ] Build passes: `bun run build --filter @reactive-agents/<pkg>`
+ ## Step 5: Docs, changeset, commit
- ## Subagent Context Template
+ `update-docs` picks the files to touch. `bun run changeset` (patch fix / minor feature / major breaking). Stage specific files, never `git add -A`; one concern per commit; no AI co-author trailers.
- When dispatching a subagent for implementation work, include this context block:
+ ## Subagent context block
```
- Project: Reactive Agents (reactive-agents-ts)
- Stack: TypeScript + Bun + Effect-TS (^3.10) + bun:test
- Key rule: All data shapes use Schema.Struct, errors use Data.TaggedError, state uses Ref, async uses Effect.tryPromise
- Tests: always --timeout 15000, always targeted file not global suite
- Required skills to load: effect-ts-patterns, [task-specific skill from routing above]
- Dead code: do not touch buildDynamicContext/buildStaticContext or context-engine.ts dead sections
- Architecture: read AGENTS.md before making changes
+ Project: reactive-agents-ts. TypeScript + Bun + Effect-TS + bun:test. Read AGENTS.md first.
+ Rules: Schema.Struct data, Data.TaggedError errors, Ref state, Effect.tryPromise async, no any.
+ Commands: bun run repo test|verify|check|find (no piped tests, no recursive grep). Skills: effect-ts-patterns, repo-tool, [task skill].
```