legendtkl self-dev — full change workflow for OpenClaudeTag
You are iterating on the OpenClaudeTag system codebase — you are part of this
system. This skill is the full-gate flow for tier-2 changes; the authoritative
routing rule lives in AGENTS.md → "Change Workflow". If a change is narrow and
low-risk, use fast-dev instead. If a fast-dev change grows into any tier-2 area
mid-flight, stop and escalate to this flow, stating why.
The detailed, worktree-safe verification order is doc/testing/self-dev-checklist.md.
Keep this skill, the .claude copy, and packages/runtime-adapters/workflows/self-dev-common.md
consistent in their design-on-demand / ADR / tier-routing wording (ADR-0001).
Phase 1 — Plan the change
- Derive a short kebab-case name for the change from the requirement.
- Study the relevant existing code and patterns before proposing anything.
- Return test cases + a concise Technical Approach to the user and wait for
confirmation before writing code:
- Test cases cover the happy path, edge cases, and error cases as a Markdown
table with columns
# | Scenario | GIVEN | WHEN | THEN. - The Technical Approach explains, at a high level, how the change fits the existing architecture: which subsystems it touches, the chosen approach versus the alternatives, the test coverage to add or adjust, and any notable risks or trade-offs.
- Do not start implementing until the user confirms or adjusts. If they adjust, update the proposal and wait again.
- Test cases cover the happy path, edge cases, and error cases as a Markdown
table with columns
- Record real architectural decisions as a concise ADR under
doc/decisions/(seedoc/decisions/README.md) — only when the change has a genuine architectural decision (a fork between viable options, a reversal of a prior decision, or a convention spanning multiple files). Otherwise skip the ADR and implement. - If requirements are ambiguous, scope has expanded significantly, or context is insufficient, stop and ask the user before proceeding.
Phase 2 — Implement by task (TDD)
- Break the work into small tasks and implement them one at a time, test-first: write the failing test, then the minimal implementation to make it pass, then refactor with tests green.
- Commit incrementally with a clear message:
git commit -m "<type>(<scope>): <summary>". Keep the change focused — no unrequested "opportunistic" edits.
Phase 3 — Verify (all gates must pass)
- Run the required gates before commit or PR:
pnpm lint pnpm build pnpm test pnpm test:integration # Postgres integration (storage + admin API) pnpm --filter @open-tag/api test:e2e - In a worktree, use the isolated wrappers for the Postgres and E2E gates
(they derive the worktree's own DB/ports and must not reuse the default ones):
pnpm test:integration:isolated # needs `pnpm db:setup:isolated` first pnpm test:e2e:isolated # start `pnpm dev:api:isolated` firstpnpm test:integrationneedsDATABASE_URLin the shell; the isolated wrapper injects the worktree DB instead. Seedoc/testing/self-dev-checklist.md. - Run the runtime's code-review gate (an independent review pass — see the runtime-specific self-dev appendix). Fix any critical/major findings, then re-run build, test, integration, and E2E. Max 3 attempts per failure, then stop and reassess.
- Run manual isolated validation when the change touches worker execution, queue dequeue, runtime-specific behavior the E2E suite doesn't exercise, Feishu card lifecycle, or background services (checklist → "When Manual Validation Is Also Required"). For console UI / web changes, validate the rendered behavior in a browser and capture a screenshot.
Phase 4 — Open a PR
- Push the branch and open a PR with the body template from
AGENTS.md("Commit and PR") anddoc/contributing/pr-guidelines.md:
The PR body states the goal, an overview, the confirmed test-case table from Phase 1, the core changes, the change type, and the pre-merge checklist (mark the integration and E2E gates passed even when satisfied via the isolated wrappers). Request the configured automated PR review.git push -u origin HEAD gh pr create --title "<type>(<scope>): <summary>" --body "<body>"
Phase 5 — Hand off
- Report the PR URL and the verification result. Do not push or merge beyond what the user asked; outward actions (push, PR, merge) are confirmed with the user.
Rules
- Follow
CLAUDE.md/AGENTS.mdconventions. All code, comments, docs, and PR text are in English. - Never modify
.env,infra/,.git/,pnpm-lock.yaml,*.key,*.pem. Never deletepnpm-lock.yaml. - Run every git command from the current worktree; never switch to the main repo dir.
- Never commit credentials, real tenant identifiers, or internal-only references.