Development workflow

English is authoritative; Chinese reference . AGENTS.md defines the rules.

1. Confirm scope and reviews

Before writing requirements for each new feature or independent change, ask which reviews to run: requirements, plan, execution, acceptance. Record the owner’s choice once in the change article. An explicit choice already given for this task is sufficient. There is no default; waivers apply only to that task. Read-only discovery may come first. Ask about unclear requirements or decisions and stop dependent work.

The initial documentation-only commit on local main was a one-time exception. The owner subsequently selected Fieldnotes and authorized local integration into main, subject to the commit checkpoint. Later changes still use sibling worktrees and PRs. No push or deployment is authorized.

2. Create a sibling worktree

After the initial commit exists, begin every change, including docs, from current main in a separate sibling worktree. In the canonical main/ directory, first check that the branch is main and the working tree is clean:

git status --short --branch

If origin is configured, update the base without a local merge commit:

git fetch origin
git merge --ff-only origin/main

Without a remote, use local main. Replace the example name and choose a suitable branch prefix (feat/, fix/, docs/, or ci/):

git worktree add -b feat/new-feature-name ../new-feature-name main
cd ../new-feature-name

Work in that directory. Do not reuse a nonempty path or force-reset a branch. Keep the canonical main/ worktree for integration and inspection; it can receive application code through later PR merges.

3. Develop through the selected gates

Keep the stage order even when reviews are waived. Record a waived gate as owner-waived, never passed. A final-only selection means one comprehensive independent review of the completed documents and delivery. Review approval does not authorize a commit or unrequested work.

Every selected reviewer must check correctness and challenge complexity from first principles: which requirement needs each part, whether a simpler solution suffices, what can be reused, and whether the maintenance cost is justified. Also assess test value, log/document value, and privacy. Resolve blockers and have the independent reviewer verify affected fixes within that review unless the owner changes the gate.

For dependency changes, follow the version policy : verify the latest stable release from official sources, pin exact versions, and record the version/date/source in the change log. Use pnpm’s --save-exact when adding packages, commit the generated lockfile, and run pnpm install --frozen-lockfile in CI. Pin runtime/build/deployment tools and Git/CI references as well. Verify compatibility and relevant builds/tests; ask the owner before selecting an older version when the latest stable release cannot be used.

4. Keep one readable change record

Use logs/changes/<stable-id>/index.md and index.zh.md, English primary and Simplified Chinese reference. Keep iterations before a PR merges in the same record; a later PR gets a new linked record. Add real PR metadata when available. Do not invent PRs, test results, or approvals.

Overview — problem, status, review selection, real PR link when available
Requirements — scope and acceptance criteria
Plan and decisions — chosen approach, meaningful alternatives, checks
Execution — delivered changes and significant findings
Acceptance — key commands, expected/actual results, limitations; local handbook delivered
  Migration — baseline, material impact and lasting upgrade/rollback instructions, or no-migration reason

Place each selected review beside its stage, or the final comprehensive review under acceptance. Record reviewer, date, verdict, scope, material findings and disposition; cite the reviewed Git revision when available. For an uncommitted baseline, identify the current document revision and scope explicitly. Changed reviewed content needs verification within the selected review; do not reuse stale passes. Appending a later section does not invalidate unchanged earlier sections.

Keep effective requirements, engineering rationale, material rejected alternatives, and useful verification. Omit conversation recaps, apologies, agent misunderstandings/corrections, clerical review churn, and repetitive progress updates. Do not omit defects or limitations that affect the delivered result. Record concise decision rationale, not raw internal reasoning or session transcripts.

Reusable guides belong in docs/; link them instead of repeating them. Add evidence/ only when an attachment is necessary to understand or verify the result. No routine stage files, manifests, snapshot archives, or whole-repository hash framework are required. The Silo design narrative informs the article format; our records retain per-change/PR identity. The separate OINK site will render these records after implementation.

All repository file references, including evidence references, must be relative. Public external sources may use HTTPS. Before publication, check prose, screenshots and attachments for private personal data, local absolute paths, credentials, private service addresses and raw sessions. Minimize/redact evidence and label redacted copies; never archive sensitive originals in the public repo.

5. Verify, preview, then commit

Every change must include a Chinese-only local acceptance handbook at .local/acceptance/<change-id>.md, including documentation changes and waived reviews. This ignored directory is outside docs/ and Hugo mounts; never commit/force-add it or link to it from public Markdown. Before handoff:

1. Identify the preceding baseline and delivered change. Write that change’s ordered instructions in its local handbook; reuse the maintained development guide instead of copying permanent setup into multiple public documents.
2. Cover prerequisites, environment/dependency/configuration changes, applicable start/stop commands, manual checks and automated commands with expected results. Docs-only work uses relevant document checks and explains non-applicable runtime steps.
3. Assess dependency/configuration/content/data/route/deployment migration. Include ordered operations, necessary backups, post-migration checks and rollback/recovery with irreversible limits. If none is needed, say “无需迁移” and why. Resolve owner decisions before dependent work.
4. Record actual results and pending items. Keep only concise evidence, key commands and material migration decisions in the public bilingual log; preserve any upgrade/rollback instructions future maintainers will need in that log or a durable guide. Public evidence must be understandable without the ignored file.
5. Link the local Chinese handbook in the final handoff. It does not sync through Git or appear on OINK; complete acceptance or save it separately before deleting the worktree. A selected acceptance reviewer checks reproducibility, migration completeness and the local/public boundary.

Run checks suited to the change; application changes require meaningful tests. Record actual results separately from planned checks. Documentation-only changes can use link, language, whitespace and privacy checks without application tests.

Use English Conventional Commits with an optional scope and an imperative subject. Multiple substantive changes require a bullet-point body:

docs(workflow): define contribution rules

- Require sibling worktrees for new changes
- Define task-specific reviews and commit checkpoints

Stage only intended paths. Inspect git diff --cached --check, git diff --cached --stat, git diff --cached --name-only, and the complete git diff --cached. Show the exact staged file list and full message, then wait for owner confirmation before every commit. Changed contents or message require a new preview and confirmation.

6. Open the PR and release

When a remote exists and publication is authorized, push the feature branch and open a PR to main; link the real PR in its log. No direct main pushes. Required checks must pass before merging. On the current GitHub Free private-repository plan, contributors must follow the PR-only policy and confirm the latest checks result manually; GitHub does not enforce rulesets on this plan. Enable remote enforcement if a supporting plan is later selected. Workflow files alone cannot enforce branch protection.

After merge, the planned CI/CD publishes the checked main revision to the portfolio and independent OINK site. CI/CD source configuration is included in the foundation. Remote rules, credentials, domains and production activation remain separate authorized work; follow the deployment guide.