Skip to content

PyModel/pythinker-code / .agents/skills/agent-core-dev

agent-core-dev

Verified

Use when developing in packages/agent-core-v2 (the DI × Scope agent engine) — adding or modifying a domain Service, choosing a LifecycleScope, wiring DI dependencies, splitting a domain across scopes, owning or migrating a config section, gating behavior behind an experimental flag, raising coded errors, working on the permission system, writing DI/Scope tests, porting business logic from agent-core (v1) to v2, triaging a main-branch commit against v2, or exposing a v2 domain over server-v2 while keeping the /api/v1 wire contract compatible with released clients. Self-contained guide organized by development stage (orient → design → implement → test → verify) plus align workflows for v1→v2 migration, main-branch commit triage, and server-v2 wire exposure; each file carries the rules, examples, and red lines for its step.

FileKindSize
SKILL.mdskill md8.8 KB
align.mdmarkdown14.9 KB
config.mdmarkdown25.6 KB
design.mdmarkdown16.4 KB
domain-boundaries.mdmarkdown10.5 KB
edge-exposure.mdmarkdown10.7 KB
orient.mdmarkdown5.5 KB
permission.mdmarkdown16.7 KB
server-align.mdmarkdown18.6 KB
service-authoring.mdmarkdown20.8 KB
telemetry.mdmarkdown8.4 KB
test.mdmarkdown15.2 KB
verify.mdmarkdown2.3 KB
# Stage 5 — Verify & submit

Run the guards and re-scan the red lines before submitting.

## Commands

Run from the package (or with `--filter @pymodel/agent-core-v2`):

- `pnpm --filter @pymodel/agent-core-v2 lint:imports` — import-boundary guard (`scripts/check-import-boundaries.mjs`). Catches v1 imports (`@pymodel/agent-core`) and kosong subtree violations.
- `pnpm --filter @pymodel/agent-core-v2 typecheck` — `tsc -p tsconfig.json --noEmit`.
- `pnpm --filter @pymodel/agent-core-v2 test` — `vitest run`.

## Changesets (when the change ships through the CLI)

If the change is user-facing and ships through the CLI, generate a changeset with the repository's `gen-changesets` skill (root `AGENTS.md` workflow). `agent-core-v2` is an internal package; if its change enters the CLI bundle, the changeset lists `@pymodel/pythinker-code` and describes the real change — do not present an internal-only change as a user-facing feature. Never write a `major` bump without explicit user confirmation.

## Pre-submit checklist

Walk the stages you touched and confirm:

- **Design** — scope follows state identity; no `Map<sessionId, …>` at `App`; dependency arrows do not make a foundational layer know an upstream one; no cycle was routed around.
- **Implement** — no `new` on `@IService`-carrying classes; `@IX` on constructor params only (service params after static params); interface + impl carry `_serviceBrand`; decorator names unique; coded errors only; flags for unreleased behavior.
- **Test** — SUT resolved by interface; stubs under `test/`; scope tests re-register after `_clearScopedRegistryForTests()`; teardown through one `DisposableStore`.
- **Files** — no comments (no JSDoc either); registration runs from the impl file's top level; the new domain is exported from `src/index.ts`.

Then re-read the [global red lines](SKILL.md#global-red-lines) once — they catch most cross-stage mistakes in a single scan.

## Red lines (this stage)

- Do not skip `lint:imports` — it is the only automated check for the v1-import ban and the kosong subtree rules.
- Do not list internal packages in a changeset when the change enters the CLI bundle — list `@pymodel/pythinker-code` and describe the real change.
- Never write a `major` changeset without explicit user confirmation.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall