development-process

Files (1)

• SKILL.md

SKILL.md (first lines)

# Development Process

## Purpose

This skill is the canonical place for Tachyon's detailed development workflow,
basic commands, quality checks, and coding conventions. `AGENTS.md` and
`CLAUDE.md` should stay small and only route agents to skills and durable docs.

When a rule is a long-lived architecture or operations decision, verify or
create an ADR with `adr-check`. When a rule is implementation design for a
specific change, create or update a DD with `design-doc`.

## Non-Negotiable Rules

- Use polite Japanese in conversation. Keep code comments and commit messages in
  English.
- Use `mise run` for project tasks. Do not use `just`.
- PRs are Ready PRs by default. Do not add `[codex]` to PR titles.
- Create Linear issues, not GitHub issues. For Codex, use `create-linear-issue`
  when available; otherwise use the Tachyon CLI issue flow.
- Do not create, change, or delete GitHub repositories directly with `gh` or the
  GitHub UI. Manage them through Terraform in `quantum-box/governance`.
- Keep everyday `gh` auth read-only or unauthenticated. Do not store `admin:org`,
  `repo`, `workflow`, or similarly broad scopes.
- Never commit secrets. Keep local credentials in ignored files such as
  `.env.local` or `.secrets.json`.

## Standard Flow

1. **Orient**
   - Run `project-status` when the current branch or task state is unclear.
   - Search related taskdocs, DDs, ADRs, and Linear references before starting.
   - Use `context-loader` for domain-specific work.
   - Before editing dependent multi-part work or an existing stack, use
     `stack-pr` to choose the owning layer and parent branch.

2. **Decide task tracking**
   - Use `taskdoc-create` for non-trivial work.
   - Taskdocs are execution logs and evidence, not durable architecture records.
   - Keep only active branch work in `docs/src/tasks/in-progress/`.

3. **Design before implementation**
   - Use `design-doc` for API, DB, UI workflow, cross-context behavior,
     authorization, billing, deployment, or operational behavior changes.
   - Use `adr-check` for long-lived architecture, provider, runtime, security,
     deployment, billing, or operating decisions.
   - Always look for existing ADRs in `docs/src/architecture/decisions/` before
     introducing a new durable rule.

4. **Implement with local patterns**
   - Use `explore` / `find-pattern` before writing unfamiliar code.
   - Use the focused implementation skills when applicable:
     `implement-usecase`, `implement-graphql-resolver`,
     `implement-rest-endpoint`, `implement-component`,
     `implement-repository`, `implement-domain-entity`, `create-migration`,
     `create-scenario-test`, and `create-storybook`.
   - Update the taskdoc with progress, decisions, checks, and evidence as work
     proceeds.

5. **Verify**
   - Run lightweight checks for the changed surface first.
   - Run build, format, lint, type checks, and tests on the host by default,
     scoped to the changed package or Rust crate when practical. macOS Docker
     virtualization overhead is not justified for ordinary validation.
   - Use `docker-ci*` only when the user explicitly requests it, CI parity
     depends on the container image, or the failure is suspected to be
     Docker-specific.
   - Check and wait for GitHub Actions CI when the user requests it or when
     its result is needed to complete the requested release or deployment.
     PRs run no CI; the hourly batch on `main` runs full CI and deploys.
     Start CI only when authorized by the user or the applicable release process.
   - Before finishing, run `mise run ci` once on the host. When it passes, the
     work is done.
   - For UI/user-flow changes, use `browser-test` or `playwright-cli`; API-only
     verification is not enough for UI changes.
   - Use real sign-in paths for browser verification unless the user explicitly
     asks for mock auth.
   - Use heavy quality skills (`rust-quality-checker`, `node-quality-checker`,
     `final-quality-gate`) only before PR/merge or when risk justifies it.

6. **Prepare Ready PR**
   - Use `task-pr-ready`; for stacked delivery also use `stack-pr`.
   - Fetch `origin/main`, confirm the target component version on `origin/main`,
     bump the target component by at least one patch version in every
     implementation PR, archive taskdocs to
     `docs/src/tasks/completed/v<pr-version>/`, update docs navigation if
     needed, and then create a Ready PR.

7. **Release work**
   - Use `task-complete` only for post-merge release work such as changelog,
     release notes, tags, and post-merge durable docs. The ordinary component
     version bump already belongs in the implementation PR.
   - Do not leave normal taskdoc archiving for merge-time cleanup.

8. **Audit lifecycle**
   - Use `taskdoc-audit` when `in-progress` grows or duplicate taskdocs are
     suspected.

## Basic Commands

Run commands from the repository root.

| Purpose | Command | Notes |
| --- | --- | --- |
| Setup | `mise install` then `mise run setup` | Install tools and dependencies. |
| Local Tachyon | `mise run up-local-tachyon` or `mise run uplt` | Preferred daily path: API/UI on host, DB/Redis in Docker. |
| Full Tachyon | `mise run up-tachyon` | Docker-based stack. |
| Library | `mise run up-library` | Library API/UI stack. |
| Infra only | `mise run docker-up` | DB/Redis/migrations/seeds without app processes. |
| Logs | `mise run docker-logs` | Tail Tachyon API/UI logs. |
| Stop | `mise run down` | Stop containers and volumes. |
| Build | `mise run build` or `pnpm run build` | Turbo build. |
| Rust check | `mise run check` | Default lightweight Rust check. |
| Rust format | `mise run fmt` | Use before PR when Rust changed. |
| Full CI | `mise run ci` | Host execution; run once before finishing. Use changed-surface checks while working. |
| Rust CI | `mise run ci-rust` | Host execution; use only when broad Rust validation is justified. |
| Node lint | `pnpm exec turbo run lint --filter=<pkg>` | Run for changed package. |
| Node types | `pnpm exec turbo run ts --filter=<pkg>` | Run for changed package. |
| Node format | `pnpm exec turbo run format --filter=<pkg>` | Use `pnpm run format:write` to fix format errors. |

From quantum-box/tachyon-skills, MIT.

More from quantum-box/tachyon-skills