6.4 KiB
Bootstrap Task: Fill Project Development Guidelines
hyb-oa binding: this generated bootstrap task is governed by
issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv
(TRELLIS1-3, TRELLIS1-4). The project-specific rules are maintained under
.trellis/spec/hyb-oa/; the generated backend/frontend scaffolds remain
secondary.
Goal
Capture project-specific Trellis specs so future agents follow hyb-oa conventions instead of generic generated placeholders.
Scope
- Bootstrap project-specific Trellis specs and confirm hyb-oa conventions.
- Treat this task as historical setup evidence after TRELLIS2.
Out Of Scope
- No OA business-code changes.
- No deployment, database write, Enterprise WeChat write or public data write.
Acceptance
- hyb-oa project specs exist under
.trellis/spec/hyb-oa/. - Future work can use task PRDs and JSONL spec context instead of generic agent memory.
Test Plan
python3 ./.trellis/scripts/task.py validate 00-bootstrap-guidelinesnode scripts/qa/check-trellis-governance.mjs
You (the AI) are running this task. The developer does not read this file.
The developer just ran trellis init on this project for the first time.
.trellis/ now exists with empty spec scaffolding, and this bootstrap task
exists under .trellis/tasks/. When they want to work on it, they should start
this task from a session that provides Trellis session identity.
Your job: help them populate .trellis/spec/ with the team's real
coding conventions. Every future AI session — this project's
trellis-implement and trellis-check sub-agents — auto-loads spec files
listed in per-task jsonl manifests. Empty spec = sub-agents write generic
code. Real spec = sub-agents match the team's actual patterns.
Don't dump instructions. Open with a short greeting, figure out if the repo has any existing convention docs (CLAUDE.md, .cursorrules, etc.), and drive the rest conversationally.
Status (update the checkboxes as you complete each item)
- Fill backend guidelines
- Fill frontend guidelines
- Add code examples
Spec files to populate
Backend guidelines
| File | What to document |
|---|---|
.trellis/spec/backend/directory-structure.md |
Where different file types go (routes, services, utils) |
.trellis/spec/backend/database-guidelines.md |
ORM, migrations, query patterns, naming conventions |
.trellis/spec/backend/error-handling.md |
How errors are caught, logged, and returned |
.trellis/spec/backend/logging-guidelines.md |
Log levels, format, what to log |
.trellis/spec/backend/quality-guidelines.md |
Code review standards, testing requirements |
Frontend guidelines
| File | What to document |
|---|---|
.trellis/spec/frontend/directory-structure.md |
Component/page/hook organization |
.trellis/spec/frontend/component-guidelines.md |
Component patterns, props conventions |
.trellis/spec/frontend/hook-guidelines.md |
Custom hook naming, patterns |
.trellis/spec/frontend/state-management.md |
State library, patterns, what goes where |
.trellis/spec/frontend/type-safety.md |
TypeScript conventions, type organization |
.trellis/spec/frontend/quality-guidelines.md |
Linting, testing, accessibility |
Thinking guides (already populated)
.trellis/spec/guides/ contains general thinking guides pre-filled with
best practices. Customize only if something clearly doesn't fit this project.
How to fill the spec
Step 1: Import from existing convention files first (preferred)
Search the repo for existing convention docs. If any exist, read them and
extract the relevant rules into the matching .trellis/spec/ files —
usually much faster than documenting from scratch.
| File / Directory | Tool |
|---|---|
CLAUDE.md / CLAUDE.local.md |
Claude Code |
AGENTS.md |
Codex / Claude Code / agent-compatible tools |
.cursorrules |
Cursor |
.cursor/rules/*.mdc |
Cursor (rules directory) |
.windsurfrules |
Windsurf |
.clinerules |
Cline |
.roomodes |
Roo Code |
.github/copilot-instructions.md |
GitHub Copilot |
.vscode/settings.json → github.copilot.chat.codeGeneration.instructions |
VS Code Copilot |
CONVENTIONS.md / .aider.conf.yml |
aider |
CONTRIBUTING.md |
General project conventions |
.editorconfig |
Editor formatting rules |
Step 2: Analyze the codebase for anything not covered by existing docs
Scan real code to discover patterns. Before writing each spec file:
- Find 2-3 real examples of each pattern in the codebase.
- Reference real file paths (not hypothetical ones).
- Document anti-patterns the team clearly avoids.
Step 3: Document reality, not ideals
Critical: write what the code actually does, not what it should do. Sub-agents match the spec, so aspirational patterns that don't exist in the codebase will cause sub-agents to write code that looks out of place.
If the team has known tech debt, document the current state — improvement is a separate conversation, not a bootstrap concern.
Quick explainer of the runtime (share when they ask "why do we need spec at all")
- Every AI coding task spawns two sub-agents:
trellis-implement(writes code) andtrellis-check(verifies quality). - Each task has
implement.jsonl/check.jsonlmanifests listing which spec files to load. - The platform hook auto-injects those spec files + the task's
prd.mdinto every sub-agent prompt, so the sub-agent codes/reviews per team conventions without anyone pasting them manually. - Source of truth:
.trellis/spec/. That's why filling it well now pays off forever.
Completion
When the developer confirms the checklist items above are done with real examples (not placeholders), guide them to run:
python3 ./.trellis/scripts/task.py finish
python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
After archive, every new developer who joins this project will get a
00-join-<slug> onboarding task instead of this bootstrap task.
Suggested opening line
"Welcome to Trellis! Your init just set me up to help you fill the project spec — a one-time setup so every future AI session follows the team's conventions instead of writing generic code. Before we start, do you have any existing convention docs (CLAUDE.md, .cursorrules, CONTRIBUTING.md, etc.) I can pull from, or should I scan the codebase from scratch?"