# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**adspecs AI Plugin** — a Claude Code / Qoder / WorkBuddy plugin for ECP (Enterprise Cloud Platform) full-lifecycle AI-driven development. Provides 30 skills (slash commands) covering requirements, SOW authoring, system design, task breakdown, unit testing, code review, feature status tracking, and wiki sync.

- **Plugin name**: `adspecs` (see `.claude-plugin/plugin.json` / `.qoder-plugin/plugin.json` / `.codebuddy-plugin/plugin.json` / `.workbuddy-plugin/plugin.json`)
- **Author**: Qingwen Chen
- **License**: Apache 2.0
- **Language**: Chinese (all documentation, templates, and skill instructions are in Chinese)
- **Runtime**: Node.js (for hook scripts only); no build system needed

## Project Structure

```
adspecs/
├── .claude-plugin/              # Plugin metadata for Claude Code
├── .qoder-plugin/               # Plugin metadata for Qoder
├── .codebuddy-plugin/           # Plugin metadata for WorkBuddy (CodeBuddy format)
├── .workbuddy-plugin/           # Plugin metadata for WorkBuddy (legacy, backward compat)
├── .adspecs/                    # Plugin runtime config, templates, scripts & extensions (copied to target projects)
│   ├── templates/               #   21 standard document templates (PRD, system design, etc.)
│   ├── extensions/              #   Extension configs (git hooks, etc.)
│   ├── scripts/                 #   Helper scripts (bash, PowerShell, Python)
│   ├── feature.json             #   Default feature tracking template (JSON, primary)
│   ├── feature.yml              #   Feature tracking human-readable view (YAML, synced from JSON)
│   ├── session-logger.json      #   AI session logger trigger configuration (keywords, auto-triggers)
│   └── project.json             #   Default project metadata template
├── skills/                      # 20 skill definitions (each with SKILL.md)
│   ├── project-init/            #   Project scaffolding
│   ├── ads-biz-analysis/    #   7-step business requirement analysis
│   ├── ads-new-requirement/ #   Deep business requirement analysis + mock review
│   ├── ads-write-sow/       #   Generate Statement of Work (SOW) from project info
│   ├── ads-prd/               #   Generate PRD from natural language
│   ├── ads-clarify/         #   Clarify ambiguities in PRD (≤5 per round)
│   ├── ads-requirement-research/  # Requirements traceability
│   ├── ads-planning/        #   3-step platform architecture planning (scenarios→dependencies→data model)
│   ├── ads-plan/            #   Backend system design (OOA+OOD) + DDL SQL
│   ├── ads-front-spec/      #   Frontend design spec (UI/interaction)
│   ├── ads-tasks/           #   Backend TDD task list
│   ├── ads-front-tasks/     #   Frontend TDD task list
│   ├── ads-analyze/         #   Cross-document consistency analysis (13 dimensions)
│   ├── ads-adversarial-review/  # Multi-role adversarial document review (5 red team roles)
│   ├── ads-git-commit/      #   Auto-commit after spec phases
│   ├── ads-utest/           #   JUnit 5 + Mockito unit test code + reports
│   ├── ads-export-word/     #   Export Markdown to Word (.docx) with cover page + TOC
│   ├── ads-update-status/   #   Feature status update + tracking matrix output
│   ├── ads-save-session/    #   Save AI session log to docs/80-development/800-log/
│   ├── sie-front-code-review/   #   React+TS+AntDesign code review
│   └── wiki-update/             #   Sync docs/ to wiki/ (full + incremental modes)
├── references/                  # Reference projects & conventions copied during `/project-init`
│   ├── docs/40-project_conventions/  #   ECP coding standards (backend + frontend integration)
│   ├── front-demo/              #   Vue 3 demo project (Vite + TS + Element Plus)
│   ├── antd-front-demo/         #   Ant Design React demo project
│   ├── web-ui/                  #   ECP management console shell project
│   ├── python/                  #   Python reference resources
│   └── yudaocloud-end-integration/  #   Yudao Cloud backend integration reference
├── hooks/                       # Node.js hook scripts + hooks.json config
├── commands/                    # Reserved (empty)
├── scripts/                     # Reserved (empty)
└── settings.json                # Plugin-level settings (currently empty)
```

## Skill System

Each skill lives in `skills/{name}/SKILL.md` with YAML frontmatter (`name`, `description`, `argument-hint`, `compatibility`, `user-invocable`, `disable-model-invocation`). Skills receive user input via `$ARGUMENTS` placeholder and are invoked as slash commands (e.g., `/project-init`, `/ads-prd`).

### Skill Pipeline (Recommended Order)

```
/project-init                    → Scaffold project structure
/ads-planning                → Platform-level architecture planning (3 steps: scenarios→dependencies→data model)
/ads-new-requirement         → Deep business requirement analysis + mock review
/ads-biz-blueprint           → Business blueprint (F1~F6 file system) from requirement analysis
/ads-prd                     → Generate PRD based on business blueprint
/ads-clarify                 → Clarify ambiguities (iterate 2-3 rounds)
/ads-biz-analysis            → Business requirement analysis (alternative entry point)
/ads-write-sow               → Author Statement of Work (SOW) from project/contract info
/ads-requirement-research    → Record requirement sources
/ads-plan                    → Backend system design + DDL SQL
/ads-front-spec              → Frontend design (UI/interaction)
/ads-tasks                   → Backend TDD task list
/ads-front-tasks             → Frontend TDD task list
/ads-analyze                 → Cross-document consistency check
/ads-adversarial-review      → Adversarial multi-role review
[coding via superpowers]          → Implementation (TDD, subagent-driven)
/ads-utest                   → Generate unit tests + reports
/ads-update-status           → Update feature.json stage status + tracking matrix (drafting→reviewing→approved)
/sie-front-code-review           → Frontend-specific code review
/ads-export-word             → Export Markdown docs to Word (.docx) with cover page + TOC
/wiki-update                     → Sync docs to wiki
```

### Extension Hooks

Skills check for `.adspecs/extensions.yml` in the target project root, supporting `before_*` / `after_*` hooks with `enabled`, `optional`, and `condition` fields. Condition evaluation is delegated to a HookExecutor (not implemented in this plugin).

## Hooks System

Hooks are configured in `hooks/hooks.json` and run as Node.js scripts. A shared platform detection module (`hooks/platform.js`) provides cross-platform compatibility between Claude Code, Qoder, and WorkBuddy:

| Event                                             | Script                    | Purpose                                                                                   |
| ------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------- |
| `SessionStart`                                    | `session-start.js`        | Injects `skills/using-adspecs/SKILL.md` as agent context (no-op if skill doesn't exist) |
| `SessionStart`                                    | `wiki-queue.js init`      | Initialize wiki update queue file in state dir                                            |
| `SessionStart`                                    | `commit-queue.js init`    | Initialize commit candidates queue file in state dir                                      |
| `SessionStart`                                    | `session-logger.js init`  | Detect unsaved previous session → inject recovery reminder or normal guidance              |
| `PreCompact`                                      | `session-logger.js mark`  | Context compaction imminent → inject urgent save reminder for agent to write log           |
| `PostToolUse` (Write/Edit/SearchReplace on code/doc files) | `wiki-queue.js enqueue` | Track changed files for wiki sync                                              |
| `PostToolUse` (Write/SearchReplace on `pipeline-manifest.json`) | `commit-queue.js enqueue` | Track completed features for commit                                        |
| `Stop`                                            | `wiki-queue.js report`    | Suggest wiki sync at session end                                                          |
| `Stop`                                            | `commit-queue.js report`  | Suggest commit at session end                                                             |
| `Stop`                                            | `session-logger.js report`| Mark session as missed if log not saved → recovery at next SessionStart                    |

### Platform Detection (`hooks/platform.js`)

- Detects platform via `ADSPECS_PLATFORM` env var, or platform-specific env vars (`CLAUDE_PLUGIN_ROOT` / `QODER_PLUGIN_ROOT` / `CODEBUDDY_PLUGIN_ROOT`)
- State directory: `.claude/` for Claude Code, `.qoder/` for Qoder, `.workbuddy/` for WorkBuddy
- Tool output files: reads `CLAUDE_TOOL_OUTPUT_FILES`, `QODER_TOOL_OUTPUT_FILES`, or `CODEBUDDY_TOOL_OUTPUT_FILES`
- Output protocol: unified `hookSpecificOutput.additionalContext` JSON stdout format

## Path Configuration

Skills support configurable output directories via `.adspecs/paths.json` in the target project root. Each skill reads this file at runtime and falls back to hardcoded defaults if the file or specific keys are missing.

### Default Configuration

```json
{
  "$schema": "adspecs plugin path configuration",
  "version": 1,
  "paths": {
    "biz_analysis_dir": "docs/00-customer-requirements",
    "architecture_dir": "docs/10-architecture",
    "research_output_dir": "docs/02-prd",
    "sow_dir": "docs/05-sow",
    "prd_dir": "docs/20-prd",
    "design_dir": "docs/30-system-design",
    "test_report_dir": "docs/80-development/802-test",
    "session_log_dir": "docs/80-development/800-log",
    "export_dir": "docs/90-export",
    "wiki_dir": "wiki"
  }
}
```

### Config Keys

| Key                   | Default                         | Used By                                                                                                                             |
| --------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `biz_analysis_dir`    | `docs/00-customer-requirements` | ads-new-requirement                                                                                                             |
| `architecture_dir`    | `docs/10-architecture`          | ads-planning (output), ads-new-requirement (input: 识别二级模块)                                                            |
| `research_output_dir` | `docs/02-prd`                   | ads-requirement-research                                                                                                        |
| `sow_dir`             | `docs/05-sow`                   | ads-write-sow                                                                                                                   |
| `prd_dir`             | `docs/20-prd`                   | ads-prd, ads-plan (input), ads-front-spec (input), wiki-update (source)                                                 |
| `design_dir`          | `docs/30-system-design`         | ads-plan (output), ads-tasks, ads-front-spec (output), ads-front-tasks, ads-utest (input), wiki-update (source) |
| `test_report_dir`     | `docs/80-development/802-test`      | ads-utest (unit test reports, saved by module subdirectory)                                                                     |
| `session_log_dir`     | `docs/80-development/800-log`   | session-logger (AI session logs, triggered by keyword / PreCompact / session end)                                                    |
| `export_dir`          | `docs/90-export`                | ads-export-word (Word 导出输出)                                                                                                 |
| `wiki_dir`            | `wiki`                          | wiki-update (output target)                                                                                                         |

`/project-init` generates this file automatically with default values. Users can edit it to customize output paths for their project structure.

## Reference Projects

`references/` (at the plugin root) contains resources copied during `/project-init`:

- **`docs/40-project_conventions/`** — ECP coding standards (backend Java + frontend integration)
- **`front-demo/`** — Vue 3 demo project (Vite + TypeScript + Element Plus) with `.claude/rules/` for `@gushen` component conventions
- **`antd-front-demo/`** — Ant Design React demo project
- **`web-ui/`** — management console shell project

Additionally, `.adspecs/` at the plugin root contains:

- **`templates/`** — 21 standard document templates (PRD, system design, task lists, test reports, security checklist, architecture docs, business proposal, etc.)
- **`extensions/`** — Extension configurations and scripts
- **`scripts/`** — Helper scripts (bash, PowerShell, Python)
- **`feature.json`** / **`project.json`** — Default project metadata templates

## Key Architecture Patterns

### TDD Pipeline

Task skills (`ads-tasks`, `ads-front-tasks`) follow strict RED→GREEN→REFACTOR ordering. Test tasks marked `[TDD]` must precede all implementation tasks within each user story phase.

### Target Project Structure

Projects initialized by this plugin follow this layout:

| Directory                      | Purpose                                            |
| ------------------------------ | -------------------------------------------------- |
| `docs/20-prd/`                 | Requirements specs (PRD)                           |
| `docs/30-system-design/`       | System design + SQL + frontend design + task lists |
| `docs/40-project_conventions/` | coding standards                                   |
| `.adspecs/templates/`          | Standard document templates                        |
| `web-ui/`                      | Frontend production project                        |
| `service/`                     | Backend Java service modules                       |
| `front-demo/`                  | PM design-phase Vue 3 demo project                 |

## External Dependencies

This plugin requires the **superpowers** plugin for coding-phase skills:
- `subagent-driven-development` — Subagent-driven parallel development
- `test-driven-development` — RED → GREEN → REFACTOR TDD cycle
- `verification-before-completion` — Pre-completion verification
- `finishing-a-development-branch` — Branch cleanup / PR creation

## publish

```bash
npm version patch --no-git-tag-version
npm publish --registry=https://registry.npmjs.org
```

## Installation & Distribution

```bash
# Claude Code: Register marketplace + install
claude plugins marketplace add <path-to>/.claude-plugin --scope user|project
claude plugins install adspecs --scope user|project

# Qoder: CLI install
adspecs plugin install --platform qoder --scope user|project

# WorkBuddy: CLI install
adspecs plugin install --platform workbuddy --scope user|project

# WorkBuddy (via CodeBuddy CLI)
codebuddy plugin install /path/to/adspecs --scope user
```