Skip to content

AGENTS.md

Latest commit

 

History

History
133 lines (84 loc) · 5.97 KB

AGENTS.md

File metadata and controls

133 lines (84 loc) · 5.97 KB
Raw

Session Onboarding

At the start or resume of any substantial Threadry work session, use the local $onboarding skill at .agents/skills/onboarding/SKILL.md before broad planning, GSD execution, UI work, or repo edits.

Run its read-only briefing script from the repo root:

python3 .agents/skills/onboarding/scripts/onboard.py

Treat the output as a compact session briefing, not as a replacement for the source documents. It should surface the current Threadry planning state, local workflow rules, and recent git context from repo-local sources.

The onboarding skill is read-only. Do not write to .planning/ or repo files during onboarding unless the user explicitly asks for that change.

These rules apply to every task in this project unless explicitly overridden. Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.

Rule 1 — Think Before Coding

State assumptions explicitly. If uncertain, ask rather than guess. Present multiple interpretations when ambiguity exists. Push back when a simpler approach exists. Stop when confused. Name what's unclear.

Rule 2 — Simplicity First

Minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. Test: would a senior engineer say this is overcomplicated? If yes, simplify.

Rule 3 — Surgical Changes

Touch only what you must. Clean up only your own mess. Don't "improve" adjacent code, comments, or formatting. Don't refactor what isn't broken. Match existing style. Never directly modify original UI components installed from shadcn/ui, including files under apps/website/src/components/ui/**. Treat them as vendor-owned source. If behavior or styling needs to change, compose or wrap the component outside the shadcn-owned file, or regenerate/update it through the shadcn CLI with explicit user approval.

Rule 4 — Goal-Driven Execution

Define success criteria. Loop until verified. Don't follow steps. Define success and iterate. Strong success criteria let you loop independently.

Rule 5 — Use the model only for judgment calls

Use me for: classification, drafting, summarization, extraction. Do NOT use me for: routing, retries, deterministic transforms. If code can answer, code answers.

Rule 6 — Token budgets are not advisory

Per-task: 4,000 tokens. Per-session: 30,000 tokens. If approaching budget, summarize and start fresh. Surface the breach. Do not silently overrun.

Rule 7 — Surface conflicts, don't average them

If two patterns contradict, pick one (more recent / more tested). Explain why. Flag the other for cleanup. Don't blend conflicting patterns.

Rule 8 — Read before you write

Before adding code, read exports, immediate callers, shared utilities. "Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.

Rule 9 — Tests verify intent, not just behavior

Tests must encode WHY behavior matters, not just WHAT it does. A test that can't fail when business logic changes is wrong.

Rule 10 — Checkpoint after every significant step

Summarize what was done, what's verified, what's left. Don't continue from a state you can't describe back. If you lose track, stop and restate.

Rule 11 — Match the codebase's conventions, even if you disagree

Conformance > taste inside the codebase. If you genuinely think a convention is harmful, surface it. Don't fork silently.

Rule 12 — Fail loud

"Completed" is wrong if anything was skipped silently. "Tests pass" is wrong if any were skipped. Default to surfacing uncertainty, not hiding it.

Threadry

Threadry is a local-first collaboration control plane for running multi-participant work inside shared threads. A local runner connects to Threadry, receives safe task and chat commands, calls user-owned providers locally, and reports only safe metadata, summaries, hashes, usage, and safe refs back to the app.

This project starts from a greenfield product definition. Build Threadry from first principles around the local collaboration loop: workspace, local runner, local provider/proxy registry, model targets, AI participants, threads, natural chat, work board, memory/tools, and opt-in diagnostics.

Core value: Users can attach a local runner, create useful AI participants, and collaborate with those participants in a thread without seeing raw infrastructure noise unless they intentionally open an inspector.

Product Constraints

  • Security boundary: Provider/proxy credentials, vendor OAuth tokens, bearer headers, full raw transcripts, raw LLM responses, and raw stdout/stderr must stay out of the Threadry server/database.
  • Architecture: Threadry is the control plane; the local runner is the execution plane. Providers and local provider proxies supply models, model targets describe runnable runner/provider/model routes, and AI participants are the visible thread collaborators.
  • UX priority: Primary UI optimizes for collaboration, not debugging. Hashes, evidence refs, redaction reports, and protocol metadata belong behind inspectors.
  • Workflow: This project is implemented with Codex CLI and GSD planning artifacts.
  • Planning privacy: .planning/ is local-only working context and must remain ignored by git.

GSD Workflow

Planning artifacts live in .planning/.

Use these entry points:

  • $gsd-discuss-phase <n> for phase context and approach discussion.
  • $gsd-ui-phase <n> before UI-heavy phases.
  • $gsd-plan-phase <n> to create executable phase plans.
  • $gsd-execute-phase <n> to execute planned phase work.
  • $gsd-progress to inspect status and next action.

Do not make broad direct repo edits outside the requested GSD workflow unless the user explicitly asks to bypass it.