Zzzz
141 lines
6.0 KiB
Markdown
141 lines
6.0 KiB
Markdown
# Bootstrap Task: Fill Project Development Guidelines
|
|
|
|
**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 task has been
|
|
set as their current task. They'll open their AI tool, run `/trellis:continue`,
|
|
and you'll land here.
|
|
|
|
**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)
|
|
|
|
- [x] Record developer-provided JSP + Servlet + MySQL + Tomcat project decisions
|
|
- [x] Fill backend guidelines with the layered B/S architecture, DAO, MySQL, service, controller, logging, and permission conventions
|
|
- [x] Fill frontend guidelines with JSP/CSS presentation conventions and the image-to-JSP restoration workflow
|
|
- [x] Preserve the note that no application source code exists yet; examples are illustrative conventions until real files are introduced
|
|
|
|
---
|
|
|
|
## Spec files to populate
|
|
|
|
|
|
### Backend guidelines
|
|
|
|
| File | What to document |
|
|
|------|------------------|
|
|
| `.trellis/spec/backend/directory-structure.md` | JSP/Servlet Java web app layering: controller, service, DAO, entity, filter, util |
|
|
| `.trellis/spec/backend/database-guidelines.md` | MySQL core tables, DAO CRUD, keys, query patterns, integrity constraints |
|
|
| `.trellis/spec/backend/error-handling.md` | Servlet validation, service failures, DAO/database exceptions, safe user results |
|
|
| `.trellis/spec/backend/logging-guidelines.md` | System logs, key operations, backup events, exception tracing |
|
|
| `.trellis/spec/backend/quality-guidelines.md` | Layer boundaries, permission checks, validation, documentation-only checks |
|
|
|
|
|
|
### Frontend guidelines
|
|
|
|
| File | What to document |
|
|
|------|------------------|
|
|
| `.trellis/spec/frontend/directory-structure.md` | JSP pages, WEB-INF organization, shared fragments, static CSS/JS/images |
|
|
| `.trellis/spec/frontend/component-guidelines.md` | JSP includes/fragments, forms, tables, reports, shared CSS conventions |
|
|
| `.trellis/spec/frontend/hook-guidelines.md` | Explicit absence of React/Vue hook conventions unless introduced later |
|
|
| `.trellis/spec/frontend/state-management.md` | Servlet/JSP request, session, database, and form state |
|
|
| `.trellis/spec/frontend/type-safety.md` | JSP/Servlet data contracts, JavaBean display, server-side validation |
|
|
| `.trellis/spec/frontend/quality-guidelines.md` | Image-first design and faithful JSP/CSS restoration workflow |
|
|
|
|
|
|
### 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) and `trellis-check` (verifies quality).
|
|
- Each task has `implement.jsonl` / `check.jsonl` manifests listing which
|
|
spec files to load.
|
|
- The platform hook auto-injects those spec files + the task's `prd.md`
|
|
into 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:
|
|
|
|
```bash
|
|
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?"
|