chore: record session journal - 握力环训练趣味化
This commit is contained in:
@@ -0,0 +1,158 @@
|
||||
---
|
||||
name: check-cross-layer
|
||||
description: "Post-implementation verification across multiple code dimensions: cross-layer data flow, code reuse analysis, import path validation, and same-layer consistency checks. Identifies missed update sites, type mismatches, and duplicated constants. Use when changes span 3+ architectural layers, after modifying shared constants or configs, after batch file modifications, or when creating new utility functions."
|
||||
---
|
||||
|
||||
# Cross-Layer Check
|
||||
|
||||
Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill.
|
||||
|
||||
> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) **before** writing code.
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
| Document | Purpose | Timing |
|
||||
|----------|---------|--------|
|
||||
| [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
|
||||
| [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation |
|
||||
| **`/check-cross-layer`** (this skill) | Verification check | **After** implementation |
|
||||
|
||||
---
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Identify Change Scope
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff --name-only
|
||||
```
|
||||
|
||||
### 2. Select Applicable Check Dimensions
|
||||
|
||||
Based on your change type, execute relevant checks below:
|
||||
|
||||
---
|
||||
|
||||
## Dimension A: Cross-Layer Data Flow (Required when 3+ layers)
|
||||
|
||||
**Trigger**: Changes involve 3 or more layers
|
||||
|
||||
| Layer | Common Locations |
|
||||
|-------|------------------|
|
||||
| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` |
|
||||
| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` |
|
||||
| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` |
|
||||
| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` |
|
||||
| Utility | `utils/`, `helpers/`, `common/` |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Read flow: Database -> Service -> API -> UI
|
||||
- [ ] Write flow: UI -> API -> Service -> Database
|
||||
- [ ] Types/schemas correctly passed between layers?
|
||||
- [ ] Errors properly propagated to caller?
|
||||
- [ ] Loading/pending states handled at each layer?
|
||||
|
||||
**Detailed Guide**: `.trellis/spec/guides/cross-layer-thinking-guide.md`
|
||||
|
||||
---
|
||||
|
||||
## Dimension B: Code Reuse (Required when modifying constants/config)
|
||||
|
||||
**Trigger**:
|
||||
- Modifying UI constants (label, icon, color)
|
||||
- Modifying any hardcoded value
|
||||
- Seeing similar code in multiple places
|
||||
- Creating a new utility/helper function
|
||||
- Just finished batch modifications across files
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Search first: How many places define this value?
|
||||
```bash
|
||||
# Search in source files (adjust extensions for your project)
|
||||
grep -r "value-to-change" src/
|
||||
```
|
||||
- [ ] If 2+ places define same value -> Should extract to shared constant
|
||||
- [ ] After modification, all usage sites updated?
|
||||
- [ ] If creating utility: Does similar utility already exist?
|
||||
|
||||
**Detailed Guide**: `.trellis/spec/guides/code-reuse-thinking-guide.md`
|
||||
|
||||
---
|
||||
|
||||
## Dimension B2: New Utility Functions
|
||||
|
||||
**Trigger**: About to create a new utility/helper function
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Search for existing similar utilities first
|
||||
```bash
|
||||
grep -r "functionNamePattern" src/
|
||||
```
|
||||
- [ ] If similar exists, can you extend it instead?
|
||||
- [ ] If creating new, is it in the right location (shared vs domain-specific)?
|
||||
|
||||
---
|
||||
|
||||
## Dimension B3: After Batch Modifications
|
||||
|
||||
**Trigger**: Just modified similar patterns in multiple files
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Did you check ALL files with similar patterns?
|
||||
```bash
|
||||
grep -r "patternYouChanged" src/
|
||||
```
|
||||
- [ ] Any files missed that should also be updated?
|
||||
- [ ] Should this pattern be abstracted to prevent future duplication?
|
||||
|
||||
---
|
||||
|
||||
## Dimension C: Import/Dependency Paths (Required when creating new files)
|
||||
|
||||
**Trigger**: Creating new source files
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Using correct import paths (relative vs absolute)?
|
||||
- [ ] No circular dependencies?
|
||||
- [ ] Consistent with project's module organization?
|
||||
|
||||
---
|
||||
|
||||
## Dimension D: Same-Layer Consistency
|
||||
|
||||
**Trigger**:
|
||||
- Modifying display logic or formatting
|
||||
- Same domain concept used in multiple places
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Search for other places using same concept
|
||||
```bash
|
||||
grep -r "ConceptName" src/
|
||||
```
|
||||
- [ ] Are these usages consistent?
|
||||
- [ ] Should they share configuration/constants?
|
||||
|
||||
---
|
||||
|
||||
## Common Issues Quick Reference
|
||||
|
||||
| Issue | Root Cause | Prevention |
|
||||
|-------|------------|------------|
|
||||
| Changed one place, missed others | Didn't search impact scope | `grep` before changing |
|
||||
| Data lost at some layer | Didn't check data flow | Trace data source to destination |
|
||||
| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions |
|
||||
| UI/output inconsistent | Same concept in multiple places | Extract shared constants |
|
||||
| Similar utility exists | Didn't search first | Search before creating |
|
||||
| Batch fix incomplete | Didn't verify all occurrences | grep after fixing |
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
Report:
|
||||
1. Which dimensions your changes involve
|
||||
2. Check results for each dimension
|
||||
3. Issues found and fix suggestions
|
||||
@@ -0,0 +1,51 @@
|
||||
# Continue Current Task
|
||||
|
||||
Resume work on the current task — pick up at the right phase/step in `.trellis/workflow.md`.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Load Current Context
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py
|
||||
```
|
||||
|
||||
Confirms: current task, git state, recent commits.
|
||||
|
||||
## Step 2: Load the Phase Index
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase
|
||||
```
|
||||
|
||||
Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
|
||||
|
||||
## Step 3: Decide Where You Are
|
||||
|
||||
Compare the task's `prd.md` + recent activity against the Phase Index:
|
||||
|
||||
- No `prd.md` yet, or requirements unclear → **Phase 1: Plan** (start at step 1.0/1.1)
|
||||
- `prd.md` exists + context configured, but code not written → **Phase 2: Execute** (step 2.1)
|
||||
- Code written, pending final quality gate → **Phase 3: Finish** (step 3.1)
|
||||
|
||||
Phase rules (full detail in `.trellis/workflow.md`):
|
||||
|
||||
1. Run steps **in order** within a phase — `[required]` steps must not be skipped
|
||||
2. `[once]` steps are already done if the output exists (e.g., `prd.md` for 1.1; `implement.jsonl` with curated entries for 1.3) — skip them
|
||||
3. You may go back to an earlier phase if discoveries require it
|
||||
|
||||
## Step 4: Load the Specific Step
|
||||
|
||||
Once you know which step to resume at:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform antigravity
|
||||
```
|
||||
|
||||
Follow the loaded instructions. After each `[required]` step completes, move to the next.
|
||||
|
||||
---
|
||||
|
||||
## Reference
|
||||
|
||||
Full workflow, skill routing table, and the DO-NOT-skip table live in `.trellis/workflow.md`. This command is only an entry point — the canonical guidance is there.
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
name: create-command
|
||||
description: "Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set."
|
||||
---
|
||||
|
||||
# Create New Workflow
|
||||
|
||||
Create a new Antigravity workflow in `.agent/workflows/<workflow-name>.md` based on user requirements.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/create-command <skill-name> <description>
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/create-command review-pr Check PR code changes against project guidelines
|
||||
```
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Parse Input
|
||||
|
||||
Extract from user input:
|
||||
- **Skill name**: Use kebab-case (e.g., `review-pr`)
|
||||
- **Description**: What the skill should accomplish
|
||||
|
||||
### 2. Analyze Requirements
|
||||
|
||||
Determine skill type based on description:
|
||||
- **Initialization**: Read docs, establish context
|
||||
- **Pre-development**: Read guidelines, check dependencies
|
||||
- **Code check**: Validate code quality and guideline compliance
|
||||
- **Recording**: Record progress, questions, structure changes
|
||||
- **Generation**: Generate docs or code templates
|
||||
|
||||
### 3. Generate Skill Content
|
||||
|
||||
Minimum `SKILL.md` structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <skill-name>
|
||||
description: "<description>"
|
||||
---
|
||||
|
||||
# <Skill Title>
|
||||
|
||||
<Instructions for when and how to use this skill>
|
||||
```
|
||||
|
||||
### 4. Create Files
|
||||
|
||||
Create:
|
||||
- `.agent/workflows/<workflow-name>.md`
|
||||
|
||||
### 5. Confirm Creation
|
||||
|
||||
Output result:
|
||||
|
||||
```text
|
||||
[OK] Created Skill: <skill-name>
|
||||
|
||||
File path:
|
||||
- .agent/workflows/<workflow-name>.md
|
||||
|
||||
Usage:
|
||||
- Trigger directly with /<workflow-name>
|
||||
- Or type / and select it
|
||||
|
||||
Description:
|
||||
<description>
|
||||
```
|
||||
|
||||
## Skill Content Guidelines
|
||||
|
||||
### [OK] Good skill content
|
||||
|
||||
1. **Clear and concise**: Immediately understandable
|
||||
2. **Executable**: AI can follow steps directly
|
||||
3. **Well-scoped**: Clear boundaries of what to do and not do
|
||||
4. **Has output**: Specifies expected output format (if needed)
|
||||
|
||||
### [X] Avoid
|
||||
|
||||
1. **Too vague**: e.g., "optimize code"
|
||||
2. **Too complex**: Single skill should not exceed 100 lines
|
||||
3. **Duplicate functionality**: Check if similar skill exists first
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
| Skill Type | Prefix | Example |
|
||||
|------------|--------|---------|
|
||||
| Session Start | `start` | `start` |
|
||||
| Pre-development | `before-` | `before-dev` |
|
||||
| Check | `check-` | `check` |
|
||||
| Record | `record-` | `record-session` |
|
||||
| Generate | `generate-` | `generate-api-doc` |
|
||||
| Update | `update-` | `update-changelog` |
|
||||
| Other | Verb-first | `review-code`, `sync-data` |
|
||||
@@ -0,0 +1,56 @@
|
||||
# Finish Work
|
||||
|
||||
Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this command.
|
||||
|
||||
## Step 1: Survey current state
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode record
|
||||
```
|
||||
|
||||
This prints:
|
||||
|
||||
- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round.
|
||||
- **Git status** — quick visual on what's dirty.
|
||||
- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
|
||||
|
||||
If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless.
|
||||
|
||||
## Step 2: Sanity check — working tree must be clean
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git status --porcelain
|
||||
```
|
||||
|
||||
Filter out paths under `.trellis/workspace/` and `.trellis/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this skill's own work.
|
||||
|
||||
If anything else is dirty (any path outside those two prefixes), **stop and bail out** with:
|
||||
|
||||
> "Working tree has uncommitted code changes. Return to workflow Phase 3.4 to commit them before running `/finish-work`."
|
||||
|
||||
Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there.
|
||||
|
||||
## Step 3: Archive task(s)
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py archive <task-name>
|
||||
```
|
||||
|
||||
At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
|
||||
|
||||
If there is no active task and the user did not confirm any cleanup archives, skip this step.
|
||||
|
||||
## Step 4: Record session journal
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/add_session.py \
|
||||
--title "Session Title" \
|
||||
--commit "hash1,hash2" \
|
||||
--summary "Brief summary"
|
||||
```
|
||||
|
||||
Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit.
|
||||
|
||||
Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: integrate-skill
|
||||
description: "Adapts an external skill into project-specific development guidelines in .trellis/spec/. Creates guideline sections, code example templates with .template suffix, and updates spec indexes. Use when integrating an external skill, adding a new skill's patterns to project conventions, or incorporating third-party skill best practices into .trellis/spec/ documentation."
|
||||
---
|
||||
|
||||
# Integrate Skill into Project Guidelines
|
||||
|
||||
Adapt and integrate a reusable skill into your project's development guidelines (not directly into project code).
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/integrate-skill <skill-name>
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
/integrate-skill frontend-design
|
||||
/integrate-skill mcp-builder
|
||||
```
|
||||
|
||||
## Core Principle
|
||||
|
||||
> [!] **Important**: The goal of skill integration is to update **development guidelines**, not to generate project code directly.
|
||||
>
|
||||
> - Guidelines content -> Write to `.trellis/spec/{target}/doc.md`
|
||||
> - Code examples -> Place in `.trellis/spec/{target}/examples/skills/<skill-name>/`
|
||||
> - Example files -> Use `.template` suffix (e.g., `component.tsx.template`) to avoid IDE errors
|
||||
>
|
||||
> Where `{target}` is `frontend` or `backend`, determined by skill type.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Read Skill Content
|
||||
|
||||
Locate and read the skill instructions:
|
||||
- `.agent/workflows/<workflow-name>.md` in the repository
|
||||
- Skill list in `AGENTS.md` (when available in current context)
|
||||
|
||||
If the skill cannot be found, ask the user for the source path or repository.
|
||||
|
||||
### 2. Determine Integration Target
|
||||
|
||||
Based on skill type, determine which guidelines to update:
|
||||
|
||||
| Skill Category | Integration Target |
|
||||
|----------------|-------------------|
|
||||
| UI/Frontend (`frontend-design`, `web-artifacts-builder`) | `.trellis/spec/frontend/` |
|
||||
| Backend/API (`mcp-builder`) | `.trellis/spec/backend/` |
|
||||
| Documentation (`doc-coauthoring`, `docx`, `pdf`) | `.trellis/` or create dedicated guidelines |
|
||||
| Testing (`webapp-testing`) | `.trellis/spec/frontend/` (E2E) |
|
||||
|
||||
### 3. Analyze Skill Content
|
||||
|
||||
Extract from the skill:
|
||||
- **Core concepts**: How the skill works and key concepts
|
||||
- **Best practices**: Recommended approaches
|
||||
- **Code patterns**: Reusable code templates
|
||||
- **Caveats**: Common issues and solutions
|
||||
|
||||
### 4. Execute Integration
|
||||
|
||||
#### 4.1 Update Guidelines Document
|
||||
|
||||
Add a new section to the corresponding `doc.md`:
|
||||
|
||||
```markdown
|
||||
@@@section:skill-<skill-name>
|
||||
## # <Skill Name> Integration Guide
|
||||
|
||||
### Overview
|
||||
[Core functionality and use cases of the skill]
|
||||
|
||||
### Project Adaptation
|
||||
[How to use this skill in the current project]
|
||||
|
||||
### Usage Steps
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
|
||||
### Caveats
|
||||
- [Project-specific constraints]
|
||||
- [Differences from default behavior]
|
||||
|
||||
### Reference Examples
|
||||
See `examples/skills/<skill-name>/`
|
||||
|
||||
@@@/section:skill-<skill-name>
|
||||
```
|
||||
|
||||
#### 4.2 Create Examples Directory (if code examples exist)
|
||||
|
||||
```bash
|
||||
# Directory structure ({target} = frontend or backend)
|
||||
.trellis/spec/{target}/
|
||||
|-- doc.md # Add skill-related section
|
||||
|-- index.md # Update index
|
||||
+-- examples/
|
||||
+-- skills/
|
||||
+-- <skill-name>/
|
||||
|-- README.md # Example documentation
|
||||
|-- example-1.ts.template # Code example (use .template suffix)
|
||||
+-- example-2.tsx.template
|
||||
```
|
||||
|
||||
**File naming conventions**:
|
||||
- Code files: `<name>.<ext>.template` (e.g., `component.tsx.template`)
|
||||
- Config files: `<name>.config.template` (e.g., `tailwind.config.template`)
|
||||
- Documentation: `README.md` (normal suffix)
|
||||
|
||||
#### 4.3 Update Index File
|
||||
|
||||
Add to the Quick Navigation table in `index.md`:
|
||||
|
||||
```markdown
|
||||
| <Skill-related task> | <Section name> | `skill-<skill-name>` |
|
||||
```
|
||||
|
||||
### 5. Generate Integration Report
|
||||
|
||||
---
|
||||
|
||||
## Skill Integration Report: `<skill-name>`
|
||||
|
||||
### # Overview
|
||||
- **Skill description**: [Functionality description]
|
||||
- **Integration target**: `.trellis/spec/{target}/`
|
||||
|
||||
### # Tech Stack Compatibility
|
||||
|
||||
| Skill Requirement | Project Status | Compatibility |
|
||||
|-------------------|----------------|---------------|
|
||||
| [Tech 1] | [Project tech] | [OK]/[!]/[X] |
|
||||
|
||||
### # Integration Locations
|
||||
|
||||
| Type | Path |
|
||||
|------|------|
|
||||
| Guidelines doc | `.trellis/spec/{target}/doc.md` (section: `skill-<name>`) |
|
||||
| Code examples | `.trellis/spec/{target}/examples/skills/<name>/` |
|
||||
| Index update | `.trellis/spec/{target}/index.md` |
|
||||
|
||||
> `{target}` = `frontend` or `backend`
|
||||
|
||||
### # Dependencies (if needed)
|
||||
|
||||
```bash
|
||||
# Install required dependencies (adjust for your package manager)
|
||||
npm install <package>
|
||||
# or
|
||||
pnpm add <package>
|
||||
# or
|
||||
yarn add <package>
|
||||
```
|
||||
|
||||
### [OK] Completed Changes
|
||||
|
||||
- [ ] Added `@@@section:skill-<name>` section to `doc.md`
|
||||
- [ ] Added index entry to `index.md`
|
||||
- [ ] Created example files in `examples/skills/<name>/`
|
||||
- [ ] Example files use `.template` suffix
|
||||
|
||||
### # Related Guidelines
|
||||
|
||||
- [Existing related section IDs]
|
||||
|
||||
---
|
||||
|
||||
## 6. Optional: Create Usage Skill
|
||||
|
||||
If this skill is frequently used, create a shortcut skill:
|
||||
|
||||
```bash
|
||||
/create-command use-<skill-name> Use <skill-name> skill following project guidelines
|
||||
```
|
||||
|
||||
## Common Skill Integration Reference
|
||||
|
||||
| Skill | Integration Target | Examples Directory |
|
||||
|-------|-------------------|-------------------|
|
||||
| `frontend-design` | `frontend` | `examples/skills/frontend-design/` |
|
||||
| `mcp-builder` | `backend` | `examples/skills/mcp-builder/` |
|
||||
| `webapp-testing` | `frontend` | `examples/skills/webapp-testing/` |
|
||||
| `doc-coauthoring` | `.trellis/` | N/A (documentation workflow only) |
|
||||
|
||||
## Example: Integrating `mcp-builder` Skill
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
.trellis/spec/backend/
|
||||
|-- doc.md # Add MCP section
|
||||
|-- index.md # Add index entry
|
||||
+-- examples/
|
||||
+-- skills/
|
||||
+-- mcp-builder/
|
||||
|-- README.md
|
||||
|-- server.ts.template
|
||||
|-- tools.ts.template
|
||||
+-- types.ts.template
|
||||
```
|
||||
|
||||
### New Section in doc.md
|
||||
|
||||
```markdown
|
||||
@@@section:skill-mcp-builder
|
||||
## # MCP Server Development Guide
|
||||
|
||||
### Overview
|
||||
Create LLM-callable tool services using MCP (Model Context Protocol).
|
||||
|
||||
### Project Adaptation
|
||||
- Place services in a dedicated directory
|
||||
- Follow existing TypeScript and type definition conventions
|
||||
- Use project's logging system
|
||||
|
||||
### Reference Examples
|
||||
See `examples/skills/mcp-builder/`
|
||||
|
||||
@@@/section:skill-mcp-builder
|
||||
```
|
||||
@@ -0,0 +1,363 @@
|
||||
---
|
||||
name: onboard
|
||||
description: "Interactive three-part onboarding for new team members to the Trellis AI-assisted workflow system. Covers core philosophy (AI memory, project-specific knowledge, context drift), system structure and command deep-dives, real-world workflow examples, and guideline customization. Use when a new developer joins the project, someone needs to understand the Trellis workflow, or project guidelines need initial setup."
|
||||
---
|
||||
|
||||
You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
|
||||
|
||||
YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each skill exists, what problem it solves at a fundamental level.
|
||||
|
||||
## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS
|
||||
|
||||
This onboarding has THREE equally important parts:
|
||||
|
||||
**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, SKILL DEEP DIVE)
|
||||
- Explain WHY this workflow exists
|
||||
- Explain WHAT each skill does and WHY
|
||||
|
||||
**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES)
|
||||
- Walk through ALL 5 examples in detail
|
||||
- For EACH step in EACH example, explain:
|
||||
- PRINCIPLE: Why this step exists
|
||||
- WHAT HAPPENS: What the skill actually does
|
||||
- IF SKIPPED: What goes wrong without it
|
||||
|
||||
**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES)
|
||||
- Check if project guidelines are still empty templates
|
||||
- If empty, guide the developer to fill them with project-specific content
|
||||
- Explain the customization workflow
|
||||
|
||||
DO NOT skip any part. All three parts are essential:
|
||||
- Part 1 teaches the concepts
|
||||
- Part 2 shows how concepts work in practice
|
||||
- Part 3 ensures the project has proper guidelines for AI to follow
|
||||
|
||||
After completing ALL THREE parts, ask the developer about their first task.
|
||||
|
||||
---
|
||||
|
||||
## CORE PHILOSOPHY: Why This Workflow Exists
|
||||
|
||||
AI-assisted development has three fundamental challenges:
|
||||
|
||||
### Challenge 1: AI Has No Memory
|
||||
|
||||
Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends.
|
||||
|
||||
**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work.
|
||||
|
||||
**The Solution**: The `.trellis/workspace/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/start` skill reads this history at session start, giving AI "artificial memory."
|
||||
|
||||
### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge
|
||||
|
||||
AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions.
|
||||
|
||||
**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules.
|
||||
|
||||
**The Solution**: The `.trellis/spec/` directory contains project-specific guidelines. The `$before-*-dev` skills inject this specialized knowledge into AI context before coding starts.
|
||||
|
||||
### Challenge 3: AI Context Window Is Limited
|
||||
|
||||
Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential.
|
||||
|
||||
**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns.
|
||||
|
||||
**The Solution**: The `/check-*` skills re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/finish-work` skill does a final holistic review.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM STRUCTURE
|
||||
|
||||
```
|
||||
.trellis/
|
||||
|-- .developer # Your identity (gitignored)
|
||||
|-- workflow.md # Complete workflow documentation
|
||||
|-- workspace/ # "AI Memory" - session history
|
||||
| |-- index.md # All developers' progress
|
||||
| +-- {developer}/ # Per-developer directory
|
||||
| |-- index.md # Personal progress index
|
||||
| +-- journal-N.md # Session records (max 2000 lines)
|
||||
|-- tasks/ # Task tracking (unified)
|
||||
| +-- {MM}-{DD}-{slug}/ # Task directory
|
||||
| |-- task.json # Task metadata
|
||||
| +-- prd.md # Requirements doc
|
||||
|-- spec/ # "AI Training Data" - project knowledge
|
||||
| |-- frontend/ # Frontend conventions
|
||||
| |-- backend/ # Backend conventions
|
||||
| +-- guides/ # Thinking patterns
|
||||
+-- scripts/ # Automation tools
|
||||
```
|
||||
|
||||
### Understanding spec/ subdirectories
|
||||
|
||||
**frontend/** - Single-layer frontend knowledge:
|
||||
- Component patterns (how to write components in THIS project)
|
||||
- State management rules (Redux? Zustand? Context?)
|
||||
- Styling conventions (CSS modules? Tailwind? Styled-components?)
|
||||
- Hook patterns (custom hooks, data fetching)
|
||||
|
||||
**backend/** - Single-layer backend knowledge:
|
||||
- API design patterns (REST? GraphQL? tRPC?)
|
||||
- Database conventions (query patterns, migrations)
|
||||
- Error handling standards
|
||||
- Logging and monitoring rules
|
||||
|
||||
**guides/** - Cross-layer thinking guides:
|
||||
- Code reuse thinking guide
|
||||
- Cross-layer thinking guide
|
||||
- Pre-implementation checklists
|
||||
|
||||
---
|
||||
|
||||
## SKILL DEEP DIVE
|
||||
|
||||
### /start - Restore AI Memory
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state?
|
||||
|
||||
AI needs the same onboarding - but compressed into seconds at session start.
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Reads developer identity (who am I in this project?)
|
||||
2. Checks git status (what branch? uncommitted changes?)
|
||||
3. Reads recent session history from `workspace/` (what happened before?)
|
||||
4. Identifies active features (what's in progress?)
|
||||
5. Understands current project state before making any changes
|
||||
|
||||
**WHY THIS MATTERS**:
|
||||
- Without /start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
|
||||
- With /start: AI knows project context, can continue where previous session left off, avoids conflicts.
|
||||
|
||||
---
|
||||
|
||||
### /before-dev - Inject Specialized Knowledge
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
|
||||
2. Loads project-specific patterns into AI's working context:
|
||||
- Component naming conventions
|
||||
- State management patterns
|
||||
- Database query patterns
|
||||
- Error handling standards
|
||||
|
||||
**WHY THIS MATTERS**:
|
||||
- Without before-dev: AI writes generic code that doesn't match project style.
|
||||
- With before-dev: AI writes code that looks like the rest of the codebase.
|
||||
|
||||
---
|
||||
|
||||
### /check - Combat Context Drift
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift."
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Re-reads the guidelines that were injected earlier
|
||||
2. Compares written code against those guidelines
|
||||
3. Runs type checker and linter
|
||||
4. Identifies violations and suggests fixes
|
||||
|
||||
**WHY THIS MATTERS**:
|
||||
- Without check-*: Context drift goes unnoticed, code quality degrades.
|
||||
- With check-*: Drift is caught and corrected before commit.
|
||||
|
||||
---
|
||||
|
||||
### /check-cross-layer - Multi-Dimension Verification
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
Most bugs don't come from lack of technical skill - they come from "didn't think of it":
|
||||
- Changed a constant in one place, missed 5 other places
|
||||
- Modified database schema, forgot to update the API layer
|
||||
- Created a utility function, but similar one already exists
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Identifies which dimensions your change involves
|
||||
2. For each dimension, runs targeted checks:
|
||||
- Cross-layer data flow
|
||||
- Code reuse analysis
|
||||
- Import path validation
|
||||
- Consistency checks
|
||||
|
||||
---
|
||||
|
||||
### /finish-work - Holistic Pre-Commit Review
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
The `/check-*` skills focus on code quality within a single layer. But real changes often have cross-cutting concerns.
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Reviews all changes holistically
|
||||
2. Checks cross-layer consistency
|
||||
3. Identifies broader impacts
|
||||
4. Checks if new patterns should be documented
|
||||
|
||||
---
|
||||
|
||||
### /record-session - Persist Memory for Future
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
All the context AI built during this session will be lost when session ends. The next session's `/start` needs this information.
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Records session summary to `workspace/{developer}/journal-N.md`
|
||||
2. Captures what was done, learned, and what's remaining
|
||||
3. Updates index files for quick lookup
|
||||
|
||||
---
|
||||
|
||||
## REAL-WORLD WORKFLOW EXAMPLES
|
||||
|
||||
### Example 1: Bug Fix Session
|
||||
|
||||
**[1/8] /start** - AI needs project context before touching code
|
||||
**[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference
|
||||
**[3/8] /before-dev** - Inject project-specific development guidelines
|
||||
**[4/8] Investigate and fix the bug** - Actual development work
|
||||
**[5/8] /check** - Re-verify code against guidelines
|
||||
**[6/8] /finish-work** - Holistic cross-layer review
|
||||
**[7/8] Human tests and commits** - Human validates before code enters repo
|
||||
**[8/8] /record-session** - Persist memory for future sessions
|
||||
|
||||
### Example 2: Planning Session (No Code)
|
||||
|
||||
**[1/4] /start** - Context needed even for non-coding work
|
||||
**[2/4] python3 ./.trellis/scripts/task.py create "Planning task" --slug planning-task** - Planning is valuable work
|
||||
**[3/4] Review docs, create subtask list** - Actual planning work
|
||||
**[4/4] /record-session (with --summary)** - Planning decisions must be recorded
|
||||
|
||||
### Example 3: Code Review Fixes
|
||||
|
||||
**[1/6] /start** - Resume context from previous session
|
||||
**[2/6] /before-dev** - Re-inject guidelines before fixes
|
||||
**[3/6] Fix each CR issue** - Address feedback with guidelines in context
|
||||
**[4/6] /check** - Verify fixes did not introduce new issues
|
||||
**[5/6] /finish-work** - Document lessons from CR
|
||||
**[6/6] Human commits, then /record-session** - Preserve CR lessons
|
||||
|
||||
### Example 4: Large Refactoring
|
||||
|
||||
**[1/5] /start** - Clear baseline before major changes
|
||||
**[2/5] Plan phases** - Break into verifiable chunks
|
||||
**[3/5] Execute phase by phase with /check-* after each** - Incremental verification
|
||||
**[4/5] /finish-work** - Check if new patterns should be documented
|
||||
**[5/5] Record with multiple commit hashes** - Link all commits to one feature
|
||||
|
||||
### Example 5: Debug Session
|
||||
|
||||
**[1/6] /start** - See if this bug was investigated before
|
||||
**[2/6] /before-dev** - Guidelines might document known gotchas
|
||||
**[3/6] Investigation** - Actual debugging work
|
||||
**[4/6] /check** - Verify debug changes do not break other things
|
||||
**[5/6] /finish-work** - Debug findings might need documentation
|
||||
**[6/6] Human commits, then /record-session** - Debug knowledge is valuable
|
||||
|
||||
---
|
||||
|
||||
## KEY RULES TO EMPHASIZE
|
||||
|
||||
1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
|
||||
2. **Guidelines before code** - `$before-*-dev` skills inject project knowledge.
|
||||
3. **Check after code** - `/check-*` skills catch context drift.
|
||||
4. **Record everything** - /record-session persists memory.
|
||||
|
||||
---
|
||||
|
||||
# PART 3: Customize Your Development Guidelines
|
||||
|
||||
After explaining Part 1 and Part 2, check if the project's development guidelines need customization.
|
||||
|
||||
## Step 1: Check Current Guidelines Status
|
||||
|
||||
Check if `.trellis/spec/` contains empty templates or customized guidelines:
|
||||
|
||||
```bash
|
||||
# Check if files are still empty templates (look for placeholder text)
|
||||
grep -l "To be filled by the team" .trellis/spec/backend/*.md 2>/dev/null | wc -l
|
||||
grep -l "To be filled by the team" .trellis/spec/frontend/*.md 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
## Step 2: Determine Situation
|
||||
|
||||
**Situation A: First-time setup (empty templates)**
|
||||
|
||||
If guidelines are empty templates (contain "To be filled by the team"), this is the first time using Trellis in this project.
|
||||
|
||||
Explain to the developer:
|
||||
|
||||
"I see that the development guidelines in `.trellis/spec/` are still empty templates. This is normal for a new Trellis setup!
|
||||
|
||||
The templates contain placeholder text that needs to be replaced with YOUR project's actual conventions. Without this, `$before-*-dev` skills won't provide useful guidance.
|
||||
|
||||
**Your first task should be to fill in these guidelines:**
|
||||
|
||||
1. Look at your existing codebase
|
||||
2. Identify the patterns and conventions already in use
|
||||
3. Document them in the guideline files
|
||||
|
||||
For example, for `.trellis/spec/backend/database-guidelines.md`:
|
||||
- What ORM/query library does your project use?
|
||||
- How are migrations managed?
|
||||
- What naming conventions for tables/columns?
|
||||
|
||||
Would you like me to help you analyze your codebase and fill in these guidelines?"
|
||||
|
||||
**Situation B: Guidelines already customized**
|
||||
|
||||
If guidelines have real content (no "To be filled" placeholders), this is an existing setup.
|
||||
|
||||
Explain to the developer:
|
||||
|
||||
"Great! Your team has already customized the development guidelines. You can start using `$before-*-dev` skills right away.
|
||||
|
||||
I recommend reading through `.trellis/spec/` to familiarize yourself with the team's coding standards."
|
||||
|
||||
## Step 3: Help Fill Guidelines (If Empty)
|
||||
|
||||
If the developer wants help filling guidelines, create a feature to track this:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "Fill spec guidelines" --slug fill-spec-guidelines
|
||||
```
|
||||
|
||||
Then systematically analyze the codebase and fill each guideline file:
|
||||
|
||||
1. **Analyze the codebase** - Look at existing code patterns
|
||||
2. **Document conventions** - Write what you observe, not ideals
|
||||
3. **Include examples** - Reference actual files in the project
|
||||
4. **List forbidden patterns** - Document anti-patterns the team avoids
|
||||
|
||||
Work through one file at a time:
|
||||
- `backend/directory-structure.md`
|
||||
- `backend/database-guidelines.md`
|
||||
- `backend/error-handling.md`
|
||||
- `backend/quality-guidelines.md`
|
||||
- `backend/logging-guidelines.md`
|
||||
- `frontend/directory-structure.md`
|
||||
- `frontend/component-guidelines.md`
|
||||
- `frontend/hook-guidelines.md`
|
||||
- `frontend/state-management.md`
|
||||
- `frontend/quality-guidelines.md`
|
||||
- `frontend/type-safety.md`
|
||||
|
||||
---
|
||||
|
||||
## Completing the Onboard Session
|
||||
|
||||
After covering all three parts, summarize:
|
||||
|
||||
"You're now onboarded to the Trellis workflow system! Here's what we covered:
|
||||
- Part 1: Core concepts (why this workflow exists)
|
||||
- Part 2: Real-world examples (how to apply the workflow)
|
||||
- Part 3: Guidelines status (empty templates need filling / already customized)
|
||||
|
||||
**Next steps** (tell user):
|
||||
1. Run `/record-session` to record this onboard session
|
||||
2. [If guidelines empty] Start filling in `.trellis/spec/` guidelines
|
||||
3. [If guidelines ready] Start your first development task
|
||||
|
||||
What would you like to do first?"
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: record-session
|
||||
description: "Records completed work progress to .trellis/workspace/ journal files after human testing and commit. Captures session summaries, commit hashes, and updates developer index files for future session context. Use when a coding session is complete, after the human has committed code, or to persist session knowledge for future AI sessions."
|
||||
---
|
||||
|
||||
[!] **Prerequisite**: This skill should only be used AFTER the human has tested and committed the code.
|
||||
|
||||
**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
|
||||
|
||||
---
|
||||
|
||||
## Record Work Progress
|
||||
|
||||
### Step 1: Get Context & Check Tasks
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode record
|
||||
```
|
||||
|
||||
[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
|
||||
- Code committed? → Archive it (don't wait for PR)
|
||||
- All acceptance criteria met? → Archive it
|
||||
- Don't skip archiving just because `status` still says `planning` or `in_progress`
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py archive <task-name>
|
||||
```
|
||||
|
||||
### Step 2: One-Click Add Session
|
||||
|
||||
```bash
|
||||
# Method 1: Simple parameters
|
||||
python3 ./.trellis/scripts/add_session.py \
|
||||
--title "Session Title" \
|
||||
--commit "hash1,hash2" \
|
||||
--summary "Brief summary of what was done"
|
||||
|
||||
# Method 2: Pass detailed content via stdin
|
||||
cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash"
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| New API | Added user authentication endpoint |
|
||||
| Frontend | Updated login form |
|
||||
|
||||
**Updated Files**:
|
||||
- `packages/api/modules/auth/router.ts`
|
||||
- `apps/web/modules/auth/components/login-form.tsx`
|
||||
EOF
|
||||
```
|
||||
|
||||
**Auto-completes**:
|
||||
- [OK] Appends session to journal-N.md
|
||||
- [OK] Auto-detects line count, creates new file if >2000 lines
|
||||
- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
|
||||
- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
|
||||
- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
|
||||
|
||||
---
|
||||
|
||||
## Script Command Reference
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
|
||||
| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
|
||||
| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
|
||||
| `python3 ./.trellis/scripts/task.py list` | List active tasks |
|
||||
@@ -0,0 +1,56 @@
|
||||
# Start Session
|
||||
|
||||
Initialize a Trellis-managed development session. This platform has no session-start hook, so manually load the equivalent context by following these steps (each one mirrors a section the hook would otherwise inject).
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Current state
|
||||
Identity, git status, current task, active tasks, journal location.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py
|
||||
```
|
||||
|
||||
## Step 2: Workflow overview
|
||||
Phase Index + skill routing table + DO-NOT-skip rules.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase
|
||||
```
|
||||
|
||||
Full guide in `.trellis/workflow.md` (read on demand).
|
||||
|
||||
## Step 3: Guideline indexes
|
||||
Discover packages + spec layers, then read each relevant index file.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
cat .trellis/spec/guides/index.md
|
||||
cat .trellis/spec/<package>/<layer>/index.md # for each relevant layer
|
||||
```
|
||||
|
||||
Index files list the specific guideline docs to read when you actually start coding.
|
||||
|
||||
## Step 4: Decide next action
|
||||
From Step 1 you know the current task. Check the task directory:
|
||||
|
||||
- **Active task + `prd.md` exists** → Phase 2 step 2.1. Load the step detail:
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform antigravity
|
||||
```
|
||||
- **Active task + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
|
||||
- **No active task** → when the user describes multi-step work, load the `trellis-brainstorm` skill to clarify requirements, then create a task via `task.py create`. For simple one-off questions or trivial edits, skip this and just answer directly — no task needed.
|
||||
|
||||
---
|
||||
|
||||
## Skill routing (quick reference)
|
||||
|
||||
| User intent | Skill |
|
||||
|---|---|
|
||||
| New feature / unclear requirements | `trellis-brainstorm` |
|
||||
| About to write code | `trellis-before-dev` |
|
||||
| Done coding / quality check | `trellis-check` |
|
||||
| Stuck / fixed same bug multiple times | `trellis-break-loop` |
|
||||
| Learned something worth capturing | `trellis-update-spec` |
|
||||
|
||||
Full rules + anti-rationalization table in `.trellis/workflow.md`.
|
||||
Reference in New Issue
Block a user