Skip to content

Commit 0cd940b

Browse files
linull24linull24
authored
Merge pull request #1 from linull24/chore/spec-migration
Chore/spec migration
2 parents 622b854 + a4b75d0 commit 0cd940b

375 files changed

Lines changed: 145806 additions & 25178 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.DS_Store‎

0 Bytes
Binary file not shown.

‎.amazonq/prompts/openspec-apply.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
description: Implement an approved OpenSpec change and keep tasks in sync.
3+
---
4+
5+
The user wants to apply the following change. Use the openspec instructions to implement the approved change.
6+
7+
<ChangeId>
8+
$ARGUMENTS
9+
</ChangeId>
10+
<!-- OPENSPEC:START -->
11+
**Guardrails**
12+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
13+
- Keep changes tightly scoped to the requested outcome.
14+
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
15+
16+
**Steps**
17+
Track these steps as TODOs and complete them one by one.
18+
1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
19+
2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
20+
3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
21+
4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
22+
5. Reference `openspec list` or `openspec show <item>` when additional context is required.
23+
24+
**Reference**
25+
- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
26+
<!-- OPENSPEC:END -->

‎.amazonq/prompts/openspec-archive.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: Archive a deployed OpenSpec change and update specs.
3+
---
4+
5+
The user wants to archive the following deployed change. Use the openspec instructions to archive the change and update specs.
6+
7+
<ChangeId>
8+
$ARGUMENTS
9+
</ChangeId>
10+
<!-- OPENSPEC:START -->
11+
**Guardrails**
12+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
13+
- Keep changes tightly scoped to the requested outcome.
14+
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
15+
16+
**Steps**
17+
1. Determine the change ID to archive:
18+
- If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
19+
- If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
20+
- Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
21+
- If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
22+
2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
23+
3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
24+
4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
25+
5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
26+
27+
**Reference**
28+
- Use `openspec list` to confirm change IDs before archiving.
29+
- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
30+
<!-- OPENSPEC:END -->

‎.amazonq/prompts/openspec-proposal.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
description: Scaffold a new OpenSpec change and validate strictly.
3+
---
4+
5+
The user has requested the following change proposal. Use the openspec instructions to create their change proposal.
6+
7+
<UserRequest>
8+
$ARGUMENTS
9+
</UserRequest>
10+
<!-- OPENSPEC:START -->
11+
**Guardrails**
12+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
13+
- Keep changes tightly scoped to the requested outcome.
14+
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
15+
- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
16+
- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
17+
18+
**Steps**
19+
1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
20+
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
21+
3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
22+
4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
23+
5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
24+
6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
25+
7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
26+
27+
**Reference**
28+
- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
29+
- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
30+
- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
31+
<!-- OPENSPEC:END -->

‎.claude/CLAUDE.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Claude Code 专用指令
2+
3+
> 本文件包含专门针对 Claude Code CLI 的工作指令。其他 AI 助手（Codex、Qwen 等）请参考各自的配置文件。
4+
5+
---
6+
7+
## 优先级声明
8+
9+
1. **顶层规则**：`AGENTS.md` → OpenSpec → 本文件
10+
2. **核心约束**：遵循 AGENTS.md 的分层提示系统（Core → Cluster → Change → Memory → OpenSpec）
11+
3. **Memory MCP 优先**：所有知识检索必须通过 memory MCP，禁止直接扫描 `openspec/**`
12+
13+
---
14+
15+
## Claude Code 特定能力
16+
17+
### 1. MCP 工具集成
18+
Claude Code 已配置以下 MCP 服务器：
19+
- **chrome-devtools**: UI 交互、截图、DOM 检查
20+
- **openrouter-gemini**: 视觉/布局分析（需配合截图）
21+
- **memory**: 知识图谱检索（Core/Cluster/Change 摘要）
22+
23+
使用原则：
24+
- UI 问题发现 → 同步至 `PLAN.md` 或对应 change
25+
- 视觉分析 → 仅用于布局/可访问性，禁止纯文本推演
26+
- Memory 检索 → 每次调用记录 URI，避免重复读取
27+
28+
### 2. 任务管理
29+
- **TodoWrite 工具**：用于规划和跟踪多步骤任务
30+
- 实时更新状态：pending → in_progress → completed
31+
- 每次只能有一个任务处于 in_progress
32+
- 完成任务后立即标记 completed，不要批量更新
33+
34+
### 3. 并行工具调用
35+
- 独立操作可在单个响应中并行调用多个工具
36+
- 依赖操作必须顺序执行（如：Write → Bash for git）
37+
- 优先使用专用工具而非 bash 命令（Read/Edit/Write vs cat/sed/echo）
38+
39+
---
40+
41+
## 工作流程
42+
43+
### 启动新任务
44+
1. 阅读 `AGENTS.md` Core Layer
45+
2. 通过 memory MCP 检索相关摘要：
46+
```
47+
- spec://core-contract, spec://core-mcp
48+
- spec://cluster/<domain>
49+
- spec://change/<id>/tasks
50+
```
51+
3. 将检索结果贴入上下文并注明 URI
52+
4. 在 `PLAN.md` 或 change `tasks.md` 记录 scope、约束、不确定点
53+
5. 使用 TodoWrite 规划任务步骤
54+
55+
### 执行中
56+
- 保持最小上下文（< 15k tokens）
57+
- 不确定时使用 AskUserQuestion 工具
58+
- MCP 发现需落地到 change/PLAN
59+
- 引用 memory 时注明 URI
60+
61+
### 完成后
62+
- 核对使用的 memory URI
63+
- 更新对应 OpenSpec 章节
64+
- 同步更新 memory MCP（递增 version）
65+
- 确认未触犯 AGENTS 禁止项
66+
67+
---
68+
69+
## 禁止事项
70+
71+
1. **禁止一次性加载全 spec**
72+
- 不得 `rg` 或读取整个 `openspec/specs/**`, `openspec/changes/**`
73+
- 仅按 memory 提供的 source 路径读取最小范围
74+
75+
2. **禁止无 change-id 修改**
76+
- 所有核心逻辑或共享模块修改必须绑定活跃 change-id
77+
- 在 `PLAN.md` 或 `tasks.md` 登记
78+
79+
3. **禁止未检索 memory 就编码**
80+
- 必须先拉取 Core/Cluster/Change 摘要
81+
- 记录检索的 URI
82+
83+
4. **禁止过度工程**
84+
- 只做请求的修改，不添加额外功能
85+
- 不重构未修改的代码
86+
- 不添加假设性的错误处理
87+
88+
---
89+
90+
## 代码规范
91+
92+
### 安全
93+
- 遵循 least privilege
94+
- 不引入未审查依赖
95+
- 防范 XSS、SQL 注入、命令注入等 OWASP Top 10 漏洞
96+
97+
### 错误处理
98+
- 关键路径需明确错误处理与回退策略
99+
- 记录异常上下文
100+
- 只在系统边界验证（用户输入、外部 API）
101+
102+
### 日志
103+
- 沿用既有 logging 规范
104+
- 避免敏感信息与噪声
105+
- 重要操作需可追踪
106+
107+
### 幂等性
108+
- 数据修改、脚本、迁移须确保重复执行安全
109+
- 无法保证时需明确前置检查与恢复机制
110+
111+
---
112+
113+
## Git 操作
114+
115+
### Commit
116+
- 仅在用户明确请求时创建 commit
117+
- 遵循仓库现有 commit message 风格
118+
- 使用 HEREDOC 传递 commit message
119+
- 包含 Co-Authored-By 标记：
120+
```
121+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
122+
123+
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
124+
```
125+
126+
### Pull Request
127+
- 分析从分支分叉点起的所有 commit（不只是最新）
128+
- 使用 `gh pr create` 创建 PR
129+
- 包含 Summary 和 Test plan
130+
- 标记 Claude Code 生成
131+
132+
---
133+
134+
## 项目特定约束
135+
136+
### UI 组件
137+
- 必须使用共享 primitives（ListSurface, FilterBar, HoverPanel, PaginationFooter）
138+
- 禁止内联 `<style>` 标签
139+
- 样式集中于 `app/src/lib/styles/**`
140+
- 使用 tokenized SCSS 变量
141+
142+
### 国际化
143+
- 禁止硬编码中文字符串
144+
- 所有 UI 文本通过 i18n 系统管理
145+
- 新组件需先添加 i18n keys
146+
147+
### 数据流
148+
- Selection matrix 是 ground truth
149+
- Solver 输出必须包含 reversible ManualUpdate plan
150+
- 所有状态变更需记录到 Action Log
151+
152+
---
153+
154+
## 快速参考
155+
156+
### Memory URI 模板
157+
- Core: `spec://core-<topic>`
158+
- Cluster: `spec://cluster/<domain>#chunk-xx`
159+
- Change: `spec://change/<id>/<file>#chunk-xx`
160+
161+
### 常用 MCP 命令
162+
```typescript
163+
// 搜索节点
164+
mcp__memory__search_nodes({ query: "keyword" })
165+
166+
// 读取完整图谱
167+
mcp__memory__read_graph()
168+
169+
// 打开特定节点
170+
mcp__memory__open_nodes({ names: ["entity-name"] })
171+
```
172+
173+
### 检查清单
174+
- [ ] 已检索相关 memory 摘要并记录 URI
175+
- [ ] 已绑定 change-id（如需修改核心逻辑）
176+
- [ ] 已在 PLAN.md 记录不确定点
177+
- [ ] 已使用 TodoWrite 跟踪任务
178+
- [ ] 代码符合安全/日志/幂等规范
179+
- [ ] UI 组件使用共享 primitives
180+
- [ ] 文本已国际化
181+
- [ ] 完成后已同步更新 OpenSpec 和 memory
182+
183+
---
184+
185+
## 术语表
186+
187+
- **Brainflow**: OpenSpec 流程（proposal → design → plan → apply → archive）
188+
- **Change**: 变更单元，位于 `openspec/changes/<id>/`
189+
- **Cluster**: 业务领域摘要（UI/Engine/Pipeline）
190+
- **Memory MCP**: 知识图谱服务器，存储 Core/Cluster/Change 摘要
191+
- **Selection Matrix**: 课程选择状态的 ground truth
192+
- **Solver**: Z3 SMT 求解器，处理排课约束
193+
194+
---
195+
196+
*最后更新: 2025-12-09*

‎.github/workflows/deploy-pages.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main, master]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
defaults:
21+
run:
22+
working-directory: app
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- uses: actions/setup-node@v4
27+
with:
28+
node-version: 20
29+
cache: npm
30+
cache-dependency-path: app/package-lock.json
31+
32+
- run: npm ci
33+
34+
- run: npm run build
35+
env:
36+
BASE_PATH: /${{ github.event.repository.name }}
37+
38+
- uses: actions/configure-pages@v5
39+
40+
- uses: actions/upload-pages-artifact@v3
41+
with:
42+
path: app/build
43+
44+
deploy:
45+
needs: build
46+
runs-on: ubuntu-latest
47+
environment:
48+
name: github-pages
49+
url: ${{ steps.deployment.outputs.page_url }}
50+
steps:
51+
- id: deployment
52+
uses: actions/deploy-pages@v4
53+

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,6 @@
55
crawler/.secrets.json
66
crawler/.secrets.yaml
77
crawler/.secrets.yml
8+
9+
# Agent temporary files
10+
agentTemps/

‎.qwen/commands/openspec-apply.toml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
description = "Implement an approved OpenSpec change and keep tasks in sync."
2+
3+
prompt = """
4+
<!-- OPENSPEC:START -->
5+
**Guardrails**
6+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
7+
- Keep changes tightly scoped to the requested outcome.
8+
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
9+
10+
**Steps**
11+
Track these steps as TODOs and complete them one by one.
12+
1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
13+
2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
14+
3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
15+
4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
16+
5. Reference `openspec list` or `openspec show <item>` when additional context is required.
17+
18+
**Reference**
19+
- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
20+
<!-- OPENSPEC:END -->
21+
"""

‎.qwen/commands/openspec-archive.toml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
description = "Archive a deployed OpenSpec change and update specs."
2+
3+
prompt = """
4+
<!-- OPENSPEC:START -->
5+
**Guardrails**
6+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
7+
- Keep changes tightly scoped to the requested outcome.
8+
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
9+
10+
**Steps**
11+
1. Determine the change ID to archive:
12+
- If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
13+
- If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
14+
- Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
15+
- If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
16+
2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
17+
3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
18+
4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
19+
5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
20+
21+
**Reference**
22+
- Use `openspec list` to confirm change IDs before archiving.
23+
- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
24+
<!-- OPENSPEC:END -->
25+
"""

0 commit comments

Comments
 (0)