Initial commit
This commit is contained in:
Zzzz
@@ -0,0 +1,5 @@
|
||||
{"file": ".trellis/spec/guides/index.md", "reason": "Shared Trellis thinking guide index for reviewing bootstrap spec quality"}
|
||||
{"file": ".trellis/spec/guides/code-reuse-thinking-guide.md", "reason": "Shared guidance for checking that specs avoid duplicated or invented conventions"}
|
||||
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Shared guidance for reviewing future backend/frontend boundary notes"}
|
||||
{"file": ".trellis/tasks/00-bootstrap-guidelines/research/repo-scan.md", "reason": "Repository scan findings to verify specs reflect the actual empty app workspace"}
|
||||
{"file": ".trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md", "reason": "Developer-provided architecture and module decisions to verify against backend/frontend specs"}
|
||||
@@ -0,0 +1,5 @@
|
||||
{"file": ".trellis/spec/guides/index.md", "reason": "Shared Trellis thinking guide index for documenting current reality without inventing conventions"}
|
||||
{"file": ".trellis/spec/guides/code-reuse-thinking-guide.md", "reason": "Shared guidance for avoiding duplicated or invented conventions while bootstrapping specs"}
|
||||
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Shared guidance for future backend/frontend cross-layer decisions"}
|
||||
{"file": ".trellis/tasks/00-bootstrap-guidelines/research/repo-scan.md", "reason": "Repository scan findings showing no application source conventions currently exist"}
|
||||
{"file": ".trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md", "reason": "Developer-provided JSP/Servlet/MySQL/Tomcat architecture, modules, and frontend workflow decisions"}
|
||||
@@ -0,0 +1,140 @@
|
||||
# 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?"
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
# Project Requirements From Developer
|
||||
|
||||
## Source
|
||||
|
||||
Captured on 2026-04-27 during the Trellis bootstrap-guidelines task from
|
||||
developer-provided project facts.
|
||||
|
||||
## Architecture And Stack
|
||||
|
||||
- The system uses B/S architecture with a typical layered design.
|
||||
- The application stack is JSP + Servlet, MySQL, Tomcat, developed in IDEA.
|
||||
- The layers are presentation, controller, business/service, DAO, and data.
|
||||
|
||||
## Data Layer
|
||||
|
||||
MySQL is the data layer and stores:
|
||||
|
||||
- Book information.
|
||||
- Book category information.
|
||||
- Reader information.
|
||||
- Borrowing records.
|
||||
- Administrator information.
|
||||
- Role and permission information.
|
||||
- System logs.
|
||||
|
||||
Core entity tables should include book information, book categories, reader
|
||||
information, borrowing records, administrators, role permissions, and system
|
||||
logs. Use primary keys and foreign keys to preserve data integrity.
|
||||
|
||||
## DAO Layer
|
||||
|
||||
The data access layer uses DAO classes to perform database CRUD. DAOs should own
|
||||
SQL/database access concerns and should not contain presentation or business
|
||||
workflow logic.
|
||||
|
||||
## Business And Service Layer
|
||||
|
||||
The service layer handles:
|
||||
|
||||
- Book warehousing/intake.
|
||||
- Borrowing and returning.
|
||||
- Inventory status updates.
|
||||
- Overdue statistics.
|
||||
- Permission checks.
|
||||
|
||||
## Controller Layer
|
||||
|
||||
Servlet controllers handle request dispatch, parameter validation, and result
|
||||
return. Controllers should coordinate request/response flow and call services
|
||||
for business behavior.
|
||||
|
||||
## Presentation Layer
|
||||
|
||||
JSP/CSS pages handle page display and user interaction.
|
||||
|
||||
The frontend approach is image-first: UI should be designed or generated as
|
||||
images first, then JSP/CSS pages should restore and implement the image
|
||||
faithfully.
|
||||
|
||||
## Core Modules
|
||||
|
||||
- Login and permission management for administrator, librarian, and reader
|
||||
roles.
|
||||
- Book information management for create, update, delete, category
|
||||
maintenance, and inventory status.
|
||||
- Reader information management for profiles, borrowing eligibility, and
|
||||
contact information.
|
||||
- Borrowing and return management for borrow, return, renew, overdue handling,
|
||||
and automatic collection status updates.
|
||||
- Book search and statistics for combined search by title, author, category,
|
||||
and ID, plus borrowing rankings, inventory reports, and overdue reports.
|
||||
- System maintenance and logs for key operation logs, data backup support, and
|
||||
exception tracing.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Repository Scan
|
||||
|
||||
## Scope
|
||||
|
||||
Scanned the workspace on 2026-04-27 while bootstrapping Trellis project guidelines.
|
||||
|
||||
## Findings
|
||||
|
||||
- The workspace root is `/mnt/d/document/mzh`.
|
||||
- `git status --short --branch` from the workspace root fails with `fatal: not a git repository`; no git metadata is available at this level.
|
||||
- The only root-level convention file discovered by the bootstrap search is `AGENTS.md`.
|
||||
- `AGENTS.md` contains Trellis-managed instructions only. It does not describe backend or frontend implementation conventions.
|
||||
- No app package manifests were found at the workspace root, including `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, or common lockfiles.
|
||||
- No application source files were found outside Trellis/Codex scaffolding at shallow workspace depth. The current files are Trellis workflow/config/scripts/specs/tasks and Codex agent configuration.
|
||||
- At initial scan time, existing `.trellis/spec/backend/*.md` and
|
||||
`.trellis/spec/frontend/*.md` files were unpopulated scaffold templates; they
|
||||
have since been populated during this bootstrap task.
|
||||
|
||||
## Later Developer Decision
|
||||
|
||||
The source scan remains accurate as a scan of files on disk, but it no longer
|
||||
means the project stack lacks a decision. The developer later provided explicit
|
||||
project requirements in
|
||||
`.trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md`.
|
||||
Future agents should combine both facts: application source code does not exist
|
||||
yet, and the intended stack is JSP + Servlet + MySQL + Tomcat with a layered
|
||||
B/S architecture.
|
||||
|
||||
## Source-Code Evidence Boundary
|
||||
|
||||
Because there is no backend or frontend application code in this workspace yet,
|
||||
the bootstrap specs should distinguish source-code evidence from
|
||||
developer-provided decisions:
|
||||
|
||||
- Backend and frontend conventions are not evidenced by source files yet.
|
||||
- The project stack and intended architecture are established by the developer:
|
||||
B/S layered JSP + Servlet + MySQL + Tomcat development in IDEA.
|
||||
- Future agents should follow the populated `.trellis/spec/` files and
|
||||
`.trellis/tasks/00-bootstrap-guidelines/research/project-requirements.md`
|
||||
for stack, module, table, and workflow decisions.
|
||||
- When new backend/frontend code is introduced, agents should update the
|
||||
matching `.trellis/spec/` files with concrete examples from that code.
|
||||
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"id": "00-bootstrap-guidelines",
|
||||
"name": "00-bootstrap-guidelines",
|
||||
"title": "Bootstrap Guidelines",
|
||||
"description": "Fill in project development guidelines for AI agents",
|
||||
"status": "completed",
|
||||
"dev_type": "docs",
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P1",
|
||||
"creator": "Zzzz",
|
||||
"assignee": "Zzzz",
|
||||
"createdAt": "2026-04-27",
|
||||
"completedAt": "2026-04-27",
|
||||
"branch": null,
|
||||
"base_branch": null,
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [
|
||||
".trellis/spec/backend/",
|
||||
".trellis/spec/frontend/"
|
||||
],
|
||||
"notes": "First-time setup task created by trellis init (fullstack project)",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in New Issue
Block a user