coding-agent-extension-worker

Category: Tools & Productivity | Uploader: code-yeongyu | Downloads: 0 | Version: v1.0（Latest）
Implements a single feature in the pi-mono `todotools` builtin extension work. Use for refactoring, continuation runtime, config resolver, prompt builder, test authoring, golden snapshots, CHANGELOG entries, and harness helpers. Does NOT do manual tmux QA.
Changelog: Source: GitHub https://github.com/code-yeongyu/senpi
Directory Structure

Current level: tree/main/.factory/skills/coding-agent-extension-worker/
📄 SKILL.md 11.2 KB
SKILL.md

---
name: coding-agent-extension-worker
description: Implements a single feature in the pi-mono `todotools` builtin extension work. Use for refactoring, continuation runtime, config resolver, prompt builder, test authoring, golden snapshots, CHANGELOG entries, and harness helpers. Does NOT do manual tmux QA.
---

# Coding Agent Extension Worker

You are implementing exactly ONE feature from `features.json` in the senpi-mono coding-agent package. Your feature has been pre-assigned — read it from `features.json`, identify it by its `id`, and focus exclusively on its `description`, `preconditions`, `expectedBehavior`, `verificationSteps`, and the assertions listed in `fulfills`.

## Context you MUST read before starting

1. **Feature spec:** `features.json` — your assigned feature only.
2. **Mission document:** `mission.md` in the mission directory — for overall context.
3. **Validation contract:** `validation-contract.md` — each ID in your feature's `fulfills` describes the exact pass/fail condition you must satisfy. Read ALL your fulfills entries before you start.
4. **Architecture:** `.factory/library/architecture.md` — the target system shape. Your work MUST conform to this.
5. **Environment notes:** `.factory/library/environment.md` — tooling quirks, forbidden patterns.
6. **User testing surface:** `.factory/library/user-testing.md` — test infrastructure conventions.
7. **Mission agents guidance:** `AGENTS.md` in the mission directory — boundaries, conventions, git safety rules.
8. **Project agents guidance:** the root `AGENTS.md` at the repo root (senpi-mono coding guidelines) — fork strategy, commit conventions, anti-patterns.

## Hard rules — never violate

- **Fork strategy:** Every change is a builtin-extension change. You may not modify `packages/ai`, `packages/agent`, `packages/tui`, `packages/web-ui`, `packages/mom`, `packages/pods`, `packages/coding-agent/src/core/settings-manager.ts`, `packages/coding-agent/src/core/extensions/types.ts`, `runner.ts`, `loader.ts`, `wrapper.ts`, or any other builtin extension besides `todotools/` and `builtin/index.ts`.
- **No type suppressions:** `any`, `as any`, `@ts-ignore`, `@ts-expect-error` are forbidden across all files in `builtin/todotools/`. Use explicit type guards instead.
- **No inline imports:** top-level ES imports only. Never `await import()` or `import("pkg").Type`.
- **No real LLM calls in tests:** always use the faux provider via `createHarness`.
- **Git safety:** only `git add <specific-path>`. Never `-A`, never `.`, never `--no-verify`, never `reset --hard`, never `checkout .`, never `clean -fd`, never `stash`.
- **Only commit files you touched in this session.** Inspect `git status` before staging.
- **No emojis** in code, commits, test names, or PR comments.
- **Biome enforced:** 3-space / tab indent matching the existing file style, 120-char line width.
- **`tsgo` enforced:** all code compiles cleanly with no diagnostics.

## Procedure

### Step 1 — Orient (≤ 5 minutes)
Read in this order: your feature entry in `features.json`, the `fulfills` assertions in `validation-contract.md`, `.factory/library/architecture.md`, `.factory/library/environment.md`, mission `AGENTS.md`, root project `AGENTS.md`. Do not start coding until you have read all of these. If anything is ambiguous or conflicts with what's on disk, return to orchestrator instead of guessing.

### Step 2 — Investigate the existing code (≤ 15 minutes)
Explore the relevant source files before writing any code:
- For refactor work: read `packages/coding-agent/src/core/extensions/builtin/todowrite.ts` (pre-refactor) AND `builtin/index.ts` (registration).
- For continuation work: read `packages/coding-agent/src/core/extensions/types.ts` (search for `agent_end`, `sendUserMessage`, `registerFlag`, `getFlag`, `BeforeAgentStartEvent`) to confirm signatures. Also read `packages/coding-agent/docs/extensions.md` sections on those APIs. Read the existing `permission-system/settings.ts` for the canonical "read settings via `SettingsManager` without widening the interface" pattern.
- For test work: read `test/suite/harness.ts`, `test/suite/todowrite-extension.test.ts`, `test/utilities.ts` to understand the faux provider pattern.

Use `Grep`, `Glob`, and `Read` tools. Prefer reading real source over trusting summaries.

### Step 3 — Plan the edits (brief)
List the files you will create, edit, or delete for this feature. Verify each is inside the allowed paths. If any file is outside the allow-list, stop and return to orchestrator.

### Step 4 — Implement
Make the edits. Match the existing code style (tabs, indent, type annotations). When you write a new module:
- Use top-level ES imports.
- Export only the public symbols your feature requires.
- Prefer small, focused functions with explicit types.
- For runtime event handlers, wrap the body in try/catch and log errors — never let a throw escape the extension API surface.
- For pure functions (config resolver, prompt builder), forbid any filesystem or process imports.

### Step 5 — Verify your feature's contract assertions
For each assertion ID in your feature's `fulfills`, confirm the evidence requirement is actually met by your implementation. Re-read the behavioral description in `validation-contract.md`. If an assertion requires a specific file, a specific grep result, a specific test outcome — satisfy it exactly.

### Step 6 — Run the verification commands
Run your feature's `verificationSteps` in the order listed. They typically include:
- File existence checks.
- Grep checks for forbidden patterns.
- Package-level vitest runs for your test files (`.factory/services.yaml` `test-coding-agent` or `test-coding-agent-file` commands).
- Full coding-agent vitest run.
- `npm run check` at the repo root.

Capture all output. If any step fails, diagnose and fix. Do NOT mark the feature done with failing verification.

### Step 7 — Review diff before commit
Run `git status` and `git diff` to inspect every change. Confirm:
- No files outside your allow-list are modified.
- No out-of-scope files are staged.
- No accidental deletions.
- No accidental large binary additions.
- No `local-ignore/` files are staged.

### Step 8 — Commit
Stage with explicit paths only. Commit with a conventional message scoped to your feature. Do not push.

### Step 9 — Handoff
Return a structured handoff (the mission runner collects this):
- `successState`: `"success"` (all assertions verified), `"partial"` (some assertions blocked, documented), or `"failure"` (unable to complete).
- `filesChanged`: the exact list of paths you created/modified/deleted.
- `verifications`: the verification commands you ran and their outcomes.
- `discoveredIssues`: anything you noticed about the codebase that's broken or concerning but outside your feature scope (do not silently ignore — surface it).
- `whatWasLeftUndone`: anything you skipped or couldn't finish inside your scope. If anything, explain why.
- `criticalContext`: anything a subsequent worker needs to know that isn't already in the architecture or environment docs.

## Mission-documented baseline failures (precedence rule)

Mission `AGENTS.md` MAY contain a section titled **"Known Pre-Existing Issues (Do Not Fix — Out of Scope)"** listing test files and case counts that are red at the mission's base commit. When such a section exists, the following rule applies and **overrides** the generic "return on out-of-scope validator failure" escalation:

1. After running the full test command, compare the **set** of failing files and the **total failing case count** against the documented baseline.
2. If the observed set is **exactly** the documented set (same files, same total count), you MAY proceed and commit. The mission has explicitly waived these failures.
3. If the observed set has **any new file**, **any new failing case in a non-baseline file**, **a higher count in any baseline file**, or **a missing failure that the baseline expected**, you MUST stop and return to orchestrator. This indicates either a regression introduced by your change or a baseline shift that needs orchestrator attention.
4. Always include the observed-vs-documented comparison in your handoff verification log so the orchestrator can audit it.

## Scoped pre-existing dirty state at session start

If `git status` at the start of your session shows uncommitted changes that are **entirely inside your assigned feature's allowed paths**, treat this as a recoverable in-progress state from a prior worker session, NOT an immediate escalation. Procedure:

1. Run `git status --short` and `git diff` (and `git diff --cached`) over the dirty files. Confirm every dirty path is inside your feature's allow-list.
2. If ANY dirty path is outside your allow-list, stop and return to orchestrator immediately — do not modify those files and do not commit them.
3. If all dirty paths are in-scope, audit the changes against your feature's `description`, `expectedBehavior`, and `fulfills`. If they are correct and complete, proceed to Step 5 (verify) and Step 6 (run verification commands), then commit them as your feature's commit.
4. If they are partially correct, finish them, then verify and commit.
5. If they are wrong or contradict the spec, return to orchestrator with a summary — do NOT silently revert another worker's intent.

Untracked files outside your feature paths (e.g., `.pi/permissions-approved.jsonl`, `.pi/settings.json`, `.sisyphus/`, `local-ignore/`) are unrelated user-local artifacts and should be ignored, never staged.

## Escalation triggers

Return control to the orchestrator immediately (do NOT attempt creative workarounds) when:
- A required ExtensionAPI does not exist with the signature you expected.
- A verification step fails for a reason outside your changes AND outside the mission-documented baseline failures (see precedence rule above).
- You encounter uncommitted changes in the working tree you did not author AND the changes are outside your feature's allowed paths (see scoped dirty state rule above).
- `npm run check` or `npm run build` fails for reasons unrelated to your edits.
- You discover an assertion in your `fulfills` that is impossible to satisfy as written.
- A boundary violation would be required to complete the feature.

## Anti-patterns to avoid

- Rewriting code that is not in your feature scope "while you're there."
- Adding new CLI flags, config keys, or events not in the architecture document.
- Using `SettingsManager` in ways that widen the upstream `Settings` interface.
- Module-level mutable state (`let currentState = ...` at the top of a file). ALL state must live inside closures.
- Using `turn_end` instead of `agent_end` for continuation (turn_end causes infinite recursion inside the tool loop).
- Using `as any` or `@ts-ignore` to "unblock" a type issue — return to orchestrator instead.
- Skipping verification "because the code looks right." Always run the tests.

## Expected duration

- Simple features (golden snapshot, changelog entry, CLI smoke): 15-30 minutes.
- Medium features (config resolver, prompt builder, harness helper): 30-60 minutes.
- Large features (full refactor, runtime handler, integration test suite): 60-120 minutes.

If your feature is running significantly over budget, stop, assess, and consider returning to the orchestrator with partial state plus a plan for breaking it down further.
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
coding-agent-extension-worker

Directory Structure

SKILL.md

Report

Notice
