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)

Record developer-provided JSP + Servlet + MySQL + Tomcat project decisions
Fill backend guidelines with the layered B/S architecture, DAO, MySQL, service, controller, logging, and permission conventions
Fill frontend guidelines with JSP/CSS presentation conventions and the image-to-JSP restoration workflow
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.

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:

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?"

6.0 KiB Raw Blame History