npm package: @ouyangfan/ai-repo-blueprint-cli
Description: Scaffold a spec-driven AI coding repository structure.
Latest version: 0.1.0

# AI_SE Repository Blueprint

This repository is a starter structure for AI-assisted, spec-driven software development.

It separates five kinds of assets:

- `spec`: what should be built and how completion is judged
- `prompt`: reusable task inputs for AI agents
- `skill`: repeatable operating procedures with constraints and output contracts
- `memory`: confirmed project facts and reusable lessons
- `doc`: long-lived human-readable documentation

It also separates `shared` assets from `local` assets:

- `shared`: team-approved, reviewable, versioned, and safe to reuse
- `local`: personal scratch space, temporary notes, and unverified working context

## What

The key directories are:

```text
.
├─ .ai/
│  ├─ shared/
│  │  ├─ context/
│  │  ├─ memory/
│  │  ├─ prompts/
│  │  ├─ skills/
│  │  └─ manifest.yaml
│  └─ local/
├─ specs/
│  ├─ features/
│  └─ templates/
└─ docs/
   ├─ architecture/
   ├─ adr/
   ├─ conventions/
   └─ runbooks/
```

Use the structure this way:

- Put executable business and engineering requirements in `specs/`
- Put repo-level AI collaboration assets in `.ai/shared/`
- Put personal notes and temporary AI working memory in `.ai/local/`
- Put stable human-facing documentation in `docs/`

## Why

This layout exists to solve common failure modes in AI coding collaboration:

- Prompt sprawl: reusable prompts and one-off prompts get mixed together
- Skill drift: team procedures exist only in chat history or personal tools
- Memory pollution: temporary debugging guesses are mistaken for repository truth
- Spec ambiguity: code is written from discussion fragments instead of an authoritative spec
- Review mismatch: implementation changes are reviewed without the acceptance criteria that justified them

The structure reduces those problems by making boundaries explicit:

- `specs/` is the execution contract
- `.ai/shared/` is the team AI method library
- `.ai/local/` is personal and intentionally disposable
- `docs/` is durable narrative documentation

## How

### 1. Start with a feature spec

Create a folder under `specs/features/`:

```text
specs/features/feat-user-search/
├─ spec.md
├─ plan.md
├─ tasks.md
├─ acceptance.md
├─ decisions.md
├─ prompts/
└─ artifacts/
```

Recommended flow:

1. Copy `specs/templates/feature-spec.md` to `specs/features/<feature-id>/spec.md`
2. Write scope, business rules, non-goals, and acceptance criteria
3. Copy `implementation-plan.md`, `tasks.md`, `acceptance.md`, and `decisions.md`
4. Implement against the spec, not against chat fragments
5. Update `docs/` or `.ai/shared/memory/` only when new information becomes stable and reusable

### 2. Treat shared AI assets like code

Anything in `.ai/shared/` should be:

- reusable by more than one person or agent
- reviewable in pull requests
- named consistently
- owned by a team or individual
- easy to read without hidden context

Each prompt, skill, or memory entry should make its scope obvious.

### 3. Keep local AI assets disposable

Use `.ai/local/` for:

- temporary notes
- personal prompt variants
- scratch plans
- unverified hypotheses
- current debugging context

Do not treat `.ai/local/` as repository truth. It is ignored by git by default.

### 4. Promote local assets into shared assets deliberately

A practical promotion rule:

1. Create or refine the asset locally
2. Reuse it at least two or three times
3. Strip out personal or feature-specific noise
4. Add metadata, examples, and input/output expectations
5. Move it into `.ai/shared/` through review

## Naming Conventions

- Feature folders: `feat-<domain>-<capability>`
- Prompt files: `<task>-prompt.md`
- Skills: one directory per skill, with `SKILL.md` as the entrypoint
- ADR files in `docs/adr/`: `ADR-<number>-<title>.md`
- Memory entries: short factual names such as `search-index-latency.md`

## Shared vs Local

Use `shared` when the content is:

- stable enough to trust
- useful to other people
- worth reviewing and preserving

Use `local` when the content is:

- temporary
- personal
- exploratory
- not yet verified

## Suggested Review Rules

- Spec changes that affect behavior should be reviewed with implementation changes
- Shared prompts should include variables and at least one usage example
- Shared skills should define inputs, steps, constraints, and output shape
- Shared memory should record facts, not guesses

## First Files To Read

For a new person or agent entering this repo:

1. `README.md`
2. `.ai/shared/context/repo-map.md`
3. `specs/README.md`
4. The active feature spec under `specs/features/`
5. Relevant documents under `docs/`

## CLI Usage (Node.js)

This repository also provides an npm-installable scaffold CLI:

- Package name: `ai-repo-blueprint-cli`
- Command: `ai-repo-blueprint`

Local usage from this repository:

```bash
npm install
node bin/ai-repo-blueprint.js --dry-run --target ../my-project
node bin/ai-repo-blueprint.js --target ../my-project
```

Install and run as a global tool:

```bash
npm install -g ai-repo-blueprint-cli
ai-repo-blueprint --target /path/to/project
```

Options:

- `--dry-run`: preview changes without writing files
- `--force`: overwrite existing files
- `--include-root-readme`: include blueprint `README.md` in target root

## Release

Release docs and checklist:

- [CHANGELOG.md](/D:/work/AI_SE/CHANGELOG.md)
- [docs/runbooks/npm-release.md](/D:/work/AI_SE/docs/runbooks/npm-release.md)

One-click commands for first release:

```bash
npm run release:v0.1.0
npm run release:v0.1.0:publish
```