# Project Experience

> Use when writing code, designing architecture, choosing dependencies, or implementing features — especially when the task involves technology or domains (C++, Qt, astronomy, desktop apps, image processing, scientific computing) with prior experience documented in the shared document hub. Also use when the user mentions starting a new project or asks you to follow their coding style.

- **Type:** Skill
- **Install:** `agentstack add skill-zeusyue-acceptance-driven-development-skill-project-experience`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ZeusYue](https://agentstack.voostack.com/s/zeusyue)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ZeusYue](https://github.com/ZeusYue)
- **Source:** https://github.com/ZeusYue/acceptance-driven-development-skill/tree/main/skills/project-experience

## Install

```sh
agentstack add skill-zeusyue-acceptance-driven-development-skill-project-experience
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Project Experience

## Overview

Read the project documentation library — a collection of structured project docs (tech stack, architecture, reusable patterns, known pitfalls, coding conventions) stored in any folder (Obsidian vault or plain directory). Before writing any code, mine these documents for constraints and patterns that generic AI assistants would miss.

**Core principle:** Past projects encode years of hard-won engineering judgment. A 3-minute read of their docs saves hours of repeating their mistakes.

**Boundary:** ADD creates, updates, and finalizes `.md` from the project-document template. `project-experience` consumes those documents, produces a briefing, and refreshes `_exp_memory.md`; it does not author project documentation.

## When to Use

```
New task received ──► Is it code/architecture/dependency related?
                              │
                    ┌─────────┴──────────┐
                    │ YES                │ NO → skip
                    ▼
             Run Phase 0.1: locate doc hub
                    │
              ┌─────┴──────┐
              ▼            ▼
     _exp_memory.md?    _exp_memory.md?
         YES              NO
          │                │
          ▼                ▼
  Phase 0.2: read    Phase 0.3: find
  cache & validate   project docs
          │                │
    ┌─────┴──────┐         ▼
    ▼            ▼    Phase 1–5 full
  Valid        Empty        │
  cache?       → treat      ▼
    │          as NO   Phase 6: save
    ▼            │     cache
 Phase 2         │        │
 (match          │        │
  cache)         │        │
    │            │        │
    └────────────┼────────┘
                 ▼
         Phase 4–5: briefing + apply
```

**Specific triggers:**
- User asks you to write, design, or implement code
- User mentions "new project", "refactor", "choose library"
- Task involves: C++, Qt, FITS, astronomy, desktop GUI, image processing, scientific computing
- User says "follow my style" or "similar to my other projects"
- You're about to make an architectural decision
- You're about to pick a dependency or library

**Skip when:**
- Task is purely conversational (answering questions, explaining concepts)
- Task is about editing markdown files, notes, or documentation
- Code task is trivial (single-line fix, typo, formatting)

## Phase 0: Locate the Document Hub — REQUIRED before all other phases

All project documents and the experience cache live under one `$DOC_HUB`, independent of code roots. Use canonical absolute paths with shell/filesystem tools; when a host accepts only workspace-relative vault paths, use that supported form without changing Hub identity.

### Step 0.1: Discover $DOC_HUB (three-tier, most reliable first)

(Expand `~` to the user's home directory — `$HOME` on Unix, `%USERPROFILE%` on Windows. Do not look for a literal `~` folder.)

1. **Read the pointer file** `~/.add-hub` — a one-line file whose content is the absolute path to `$DOC_HUB`.
   - **Exists** → read and trim the path. If the directory exists, the pointer is valid and `$DOC_HUB` = that path; go to Step 0.2. `_exp_memory.md` is a cache, not a hub-identity requirement. If the path is missing or is not a directory → the pointer is stale; ignore it and fall through to tier 2 (which will rewrite `~/.add-hub`).
   - **Not found** → try tier 2.
2. **Fallback search** `Glob pattern="**/_exp_memory.md" path="~"` — the cache anchor.
   - **Found** → `$DOC_HUB` = the directory containing `_exp_memory.md`. If multiple match: prefer the directory that also contains project subfolders with `AC.md` or holds `ac-template.md`/`project-index.md`; if still ambiguous, ask the user which to use before proceeding. **Write `~/.add-hub`** with the chosen path so future sessions skip the search (never write the pointer from an ambiguous, unconfirmed match). Go to Step 0.2.
   - **Not found** → tier 3.
3. **Ask the user once:** "I need a central directory to store acceptance criteria and project experience for ALL your projects. This directory will be shared across projects, so pick a stable location — don't put it inside a specific project folder. Suggested: ~/project-docs/ (just give me the path; I'll create the needed files there.)"
   → `$DOC_HUB` = user's answer. Then perform ALL THREE actions in order (none optional):
   1. Create the directory `$DOC_HUB` if it doesn't exist.
   2. Create `$DOC_HUB/_exp_memory.md` with content `# Project Experience Cache\n\n> No completed projects yet.`
   3. **Write `~/.add-hub`** — a one-line file whose entire content is the absolute `$DOC_HUB` path. This is what lets every future session find the hub by a single direct read. Skipping this step means the next session has to ask the user again.

### Step 0.2: Check experience cache

**Forced rebuild:** If the user explicitly says "update experience cache", "refresh experience cache", or "rebuild experience cache", or ADD invokes this skill after project completion with a forced-rebuild request, keep `$DOC_HUB` fixed, skip the cache fast path, and run the full Phase 1–5 extraction. Preserve the old cache until the new cache is written successfully.

**Legacy cache fallback:** A cache without schema-2 frontmatter remains readable if it contains non-empty `## Known Pitfalls` and `## Reusable Patterns` sections. Match it by keywords only, state that provenance metadata is unavailable, and do not rewrite it unless the user explicitly requests a forced rebuild.

Otherwise check whether `$DOC_HUB/_exp_memory.md` exists:

- **YES (schema 2)** → read its `cache_schema`, `generated_at`, source-project metadata, entry tags, and source status. Match structured tags before free-text keywords, then go directly to Phase 2.
- **YES (legacy)** → use the Legacy cache fallback above.
- **NO / invalid** → remain in this same `$DOC_HUB` and proceed with full Phase 1–5. After Phase 5, save the cache atomically (see Phase 6). Do not rediscover the Hub merely because the cache is absent.

### Step 0.3: Find project documents

Project docs live at `$DOC_HUB//.md`.

`Glob pattern="$DOC_HUB/*/*.md"` lists all projects. If the user mentioned a specific project name, target that one. Otherwise scan all.
Filter results: keep only files matching `/.md` (the file named after its containing directory). Ignore AC.md, design.md, or other supplementary files — those are read separately when needed.
Store `$DOC_HUB` for all subsequent paths.

## Phase 1: Survey

Read the project index (`$DOC_HUB/project-index.md`) if it exists.

If Step 0.3 already produced the filtered project list, reuse it — skip the glob below. Otherwise run a direct file listing:

```
Glob pattern="$DOC_HUB/*/*.md"
```

Filter to project docs only: keep files matching `/.md` (named after their containing directory). Ignore `AC.md`, `design.md`, `ac-template.md`, `project-doc-template.md`, `project-index.md`.

From the survey, extract for every project document:
- Project name and document path
- Frontmatter tags, `status`, and `date`
- Document modification time
- Whether the document is active (`开发中` / `维护中` or `active` / `maintained`) or settled (`已完成` / `归档` or `completed` / `archived`)

A Dataview-only `project-index.md` is navigation metadata, not a query result available to non-Obsidian hosts. Do not rely on it for project counts, tags, or status; scan actual project-document frontmatter instead.

This takes under 15 seconds.

## Phase 2: Match — Find Relevant Projects

**If reading from a schema-2 cache:** first match entry tags against the task’s technology, domain, and capability needs; then use free-text keywords as a tie-breaker. Return only the strongest matches. If no entry matches, state this explicitly and proceed with generic best practices.

**If reading from a legacy cache:** use keyword/context matching only and say that source metadata is unavailable. If no entry matches, state this explicitly and proceed with generic best practices.

**If running the full cycle:** read the frontmatter tags of each project document and compare against the current task:

| Match dimension | How to check | Example |
|-----------------|-------------|---------|
| **Technology stack** | Same language, framework, build system | Qt + C++ task → match EgainMeasure, FitsCompare |
| **Domain** | Same industry, data format, problem type | FITS astronomy task → match both projects |
| **Architecture style** | Same pattern (MVC, pipeline, event-driven) | Desktop GUI → match Qt projects |
| **Pattern reuse** | Task needs a specific pattern | Async processing → check Generation Counter in both projects |

**Match threshold:** One dimension match = read that project. Two or more = mandatory deep read. If zero matches across all dimensions, state this explicitly and proceed with generic best practices.

## Phase 3: Extract — Targeted Reading

**Read only the sections relevant to the current task** (targeted reading saves time and context):

| Current task needs... | Read these sections |
|----------------------|---------------------|
| Choose tech stack / dependencies | Tech Stack, Key Dependencies |
| Design architecture | Architecture, Data Flow, Core Modules |
| Write async/multi-threaded code | Reusable Patterns, Edge Cases & Defensive Design |
| Handle file I/O / external libraries | Edge Cases & Defensive Design, Key Dependencies |
| Avoid known pitfalls | Technical Debt & Risks (especially ✅ resolved items) |
| Write tests | Testing |
| Set up build config | Configuration, Quick Start |
| Match author's coding style | Architecture, Core Modules, Overall Assessment |
| Export/report generation | Key Business Flows |
| Cross-project consistency | Related Projects |

**Extraction budget:** all project documents receive a lightweight extraction of frontmatter plus the sections for Tech Stack, Reusable Patterns, Technical Debt/Risks, Edge Cases, and Key Dependencies when present. Read at most 2 project documents fully; choose the most relevant by match threshold. This keeps cache coverage broad without spending full-document context on every project.

**Development-project evidence gate:** A document with `status: 开发中`, `维护中`, `active`, or `maintained` may contribute only facts evidenced by code, configuration, tests, or a resolved incident. Label its source status in the cache. Planned features, guessed architecture, and unverified ideas must not become `Known Pitfalls` or `Reusable Patterns`.

## Phase 4: Synthesize — Write the Experience Briefing

Compose a briefing and output it to the conversation. It serves as a persistent reference for the rest of the session:

```markdown
## Project Experience Briefing

### Matched Projects
- [[Project A]] — match: Qt + C++ + domain X
- [[Project B]] — match: Qt + C++ + domain Y

### Coding Preferences
1. [preference 1] — evidence: Project A Architecture, Project B Core Modules
2. [preference 2] — evidence: [source]

### Pitfalls to Avoid
| Pitfall | Status | Source | Strategy |
|---------|--------|--------|----------|
| ... | ✅/⚠️ | ... | ... |

### Reusable Patterns
1. **[pattern name]** — [one line] — applies to: [X]
2. ...

### Quality Baseline
- Code organization: [inferred]
- Error handling: [inferred]
- Test coverage: [inferred]
```

**When reading from cache (Step 0.2 = YES), use this bounded briefing format** — return at most 2 pitfalls, 2 patterns, and 2 conventions. Preserve each entry’s tags, source project(s), and active/settled source status when schema 2 provides them:

```markdown
## Project Experience Briefing (from cache)

### Relevant Pitfalls
- **pitfall** `[tags]` — strategy (Sources: ProjectA [已完成])

### Relevant Patterns
- **pattern** `[tags]` — how to apply (Sources: ProjectB [开发中], ProjectC [已完成])

### Coding Conventions
- convention `[tags]` — source
```markdown
## Project Experience Briefing (from cache)

### Relevant Pitfalls
- **pitfall**: strategy to avoid (from cached experience)

### Relevant Patterns
- **pattern**: how to apply (from cached experience)

### Coding Conventions
- convention (from cached experience)
```

## Phase 5: Apply

The briefing is your constraint system. For every subsequent decision:

1. **Choose a library** → check Pitfalls to Avoid
2. **Design a module** → check Reusable Patterns
3. **Write boilerplate** → check Coding Preferences
4. **In doubt** → cache mode: first re-read `$DOC_HUB/_exp_memory.md`; if still unclear, locate the project documents sourcing that entry and read `$DOC_HUB//.md`. If source projects can't be identified, state uncertainty explicitly.

**Reference the briefing explicitly in your responses:**

> "I see you used Generation Counter in Project A and Project B for async race conditions — I'll use the same approach here."

## Phase 6: Save Experience Cache

After completing the full extraction cycle (Phases 1–5), save the distilled experience to `$DOC_HUB/_exp_memory.md`:

```markdown
---
cache_schema: 2
generated_at: YYYY-MM-DD
source_projects:
  - name: ProjectA
    status: 已完成
    document_mtime: YYYY-MM-DD
  - name: ProjectB
    status: 开发中
    document_mtime: YYYY-MM-DD
---

# Project Experience Cache

> Auto-generated from evidence-backed project documents. Refresh with an explicit "update experience cache" request; replacement is atomic.

## Known Pitfalls

- **brief description** `[Qt, C++, Windows]`: symptom → root cause → fix (Sources: ProjectA [已完成], ProjectB [开发中])

## Reusable Patterns

- **Pattern Name** `[Qt, C++, async]`: what it solves → how it works (Sources: ProjectA [已完成], ProjectB [开发中])

## Coding Conventions

- convention description `[Qt, C++]` (Sources: ProjectA [已完成])
```

**Content rules:**
- **Known Pitfalls**: Only bugs you actually encountered and spent time fixing. Include symptom, root cause, fix, tags, and source project/status. Merge two pitfalls when they share the same root cause AND the same fix pattern. If root cause differs but symptom is similar → keep separate. If a source project is active, include it only when the incident and fix are directly evidenced.
- **Reusable Patterns**: Only patterns observed in ≥2 projects, or highly generalizable single-project patterns. A single-project pattern qualifies as highly generalizable only if it would apply to any project in the same language/framework. Ask: "Would this pattern be useful in a completely different domain app using the same tech stack?" Exclude project-specific glue code. Include what problem it solves, how it works, tags, and source project/status. Active-project sources require direct code/config/test evidence.
- **Coding Conventions**: Only preferences stable across projects. List only conventions that differ from common defaults — skip universal ones.
- **Hard cap**: Keep the entire file under ~55 lines, including frontmatter. If exceeding, apply in order: (1) Merge pitfalls with identical fix patterns even if symptoms differ. (2) Drop single-project patterns not meeting the generalizable test. (3) Drop conventions already common practice. (4) Drop least frequently applicable entries (count projects that exhibited the pattern/pitfall). Priority to keep: pitfalls > patterns > conventions.

**Atomic save rule:** Render the complete refreshed cache to `$DOC_HUB/_exp_memory.md.tmp`, validate that it contains the required headings, then replace `$DOC_HUB/_exp_memory.md` in one operation. If rendering or validation fails, retain the old cache and report the failure.

**This cache is read by future invocations** — if it exists, Phase 1 and Phase 3 are skipped unless a forced rebuild was requested (see Step 0.2). When new projects are completed, the user can request "update experience cache"; ADD Phase 6 issues that request after explicit user approval. Cache regeneration remains a human-approved action.

## Quick Reference

| Phase | Action | Time |
|-------|--------|------|
| 0. Locate | Read ~/.add-hub (existing directory is authoritative) → fallback glob only when pointer is absent/invalid → ask user | 2s |
| 0.2 Cache | Valid cac

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ZeusYue](https://github.com/ZeusYue)
- **Source:** [ZeusYue/acceptance-driven-development-skill](https://github.com/ZeusYue/acceptance-driven-development-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zeusyue-acceptance-driven-development-skill-project-experience
- Seller: https://agentstack.voostack.com/s/zeusyue
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.