TRELLIS1 迁移 Trellis 主导开发流程

2026-05-26 09:28:51 +08:00
@@ -0,0 +1,145 @@
+# 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.
+
+**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) 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?"
@@ -0,0 +1,35 @@
+{
+  "id": "00-bootstrap-guidelines",
+  "name": "00-bootstrap-guidelines",
+  "title": "Bootstrap Guidelines",
+  "description": "Fill in project development guidelines for AI agents",
+  "status": "in_progress",
+  "dev_type": "docs",
+  "scope": null,
+  "package": null,
+  "priority": "P1",
+  "creator": "shunli",
+  "assignee": "shunli",
+  "createdAt": "2026-05-26",
+  "completedAt": null,
+  "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; governed by TRELLIS1 and superseded by hyb-oa specs.",
+  "meta": {
+    "issueCsv": "issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv",
+    "issueIds": [
+      "TRELLIS1-3",
+      "TRELLIS1-4"
+    ]
+  }
+}
@@ -0,0 +1,2 @@
+{"file":".trellis/spec/hyb-oa/project-governance.md","reason":"Check task-to-Issue governance and completion rules."}
+{"file":".trellis/spec/hyb-oa/security-privacy.md","reason":"Check Trellis task files for sensitive-data violations."}
@@ -0,0 +1,3 @@
+{"file":".trellis/spec/hyb-oa/project-governance.md","reason":"Defines Trellis-first flow and Issue CSV binding rules."}
+{"file":".trellis/spec/hyb-oa/docs-and-evidence.md","reason":"Defines docs/evidence reuse and registration requirements."}
+{"file":".trellis/spec/hyb-oa/security-privacy.md","reason":"Defines redaction and sensitive-data exclusions for Trellis task files."}
@@ -0,0 +1,29 @@
+# TRELLIS1 Low-risk Pilot
+
+## Goal
+
+Prove that future hyb-oa development can start from a Trellis task while still
+binding to Issue CSV and project documentation.
+
+## Issue Binding
+
+- Issue CSV: `issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv`
+- Issue ID: `TRELLIS1-7`
+
+## Scope
+
+- Create Trellis task metadata, PRD and context manifests.
+- Reference project governance specs.
+- Run `scripts/qa/check-trellis-governance.mjs`.
+
+## Out Of Scope
+
+- No backend or frontend business-code changes.
+- No deployment.
+- No public OA data writes.
+
+## Acceptance
+
+- The task contains issue binding and redacted scope.
+- `implement.jsonl` and `check.jsonl` include real spec context entries.
+- Trellis governance check passes.
@@ -0,0 +1,35 @@
+{
+  "id": "trellis1-pilot",
+  "name": "trellis1-pilot",
+  "title": "TRELLIS1 low-risk pilot",
+  "description": "Low-risk task used to prove the Trellis task -> Issue CSV -> governance check path without changing business code.",
+  "status": "in_progress",
+  "dev_type": "docs",
+  "scope": "trellis-governance",
+  "package": "docs",
+  "priority": "P2",
+  "creator": "shunli",
+  "assignee": "shunli",
+  "createdAt": "2026-05-26",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    ".trellis/workflow.md",
+    ".trellis/spec/hyb-oa/",
+    "issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv"
+  ],
+  "notes": "No business code, no deployment, no public OA writes.",
+  "meta": {
+    "issueCsv": "issues/2026-05-26_09-02-34-trellis-primary-development-workflow-v1.csv",
+    "issueIds": [
+      "TRELLIS1-7"
+    ]
+  }
+}