# yori

[English](README.md) | [日本語](README.ja.md)

A harness engineering knowledge base for AI co-development.
Collects design principles, templates, and patterns applicable across all project types.

```
yori (this repository)
  = Harness blueprint & template collection

Each project's .opencode/
  = The actual working harness

Simply "placing" yori in a project does nothing.
The harness only starts working after running setup-harness.sh
to copy templates and filling in project-specific information.
```

---

## Quick Start

### Method A: curl (no Node.js required, recommended)

```bash
# Run in your target project root
bash <(curl -s https://raw.githubusercontent.com/Yoshi-Dai-1/yori/main/opencode/setup-harness.sh)
```

The script automatically clones yori temporarily and expands the templates.

> **Windows notes**:
> The `bash` command above requires WSL2 (Windows Subsystem for Linux) or Git Bash.
>
> **WSL2 (recommended)**:
> ```
> wsl --install            # first time only (admin PowerShell)
> ```
> Then run curl/npm/git clone inside the WSL bash shell.
>
> **Git Bash**:
> Install Git for Windows, then run curl/npm/git clone from Git Bash terminal.
>
> **npm method**: `npx @yoshi-dai/yori` automatically launches `setup-harness.ps1` (WSL2 wrapper) on Windows.

### Method B: npm

```bash
npx @yoshi-dai/yori
```

### Method C: git clone

```bash
git clone https://github.com/Yoshi-Dai-1/yori.git
cd your-target-project
bash ../yori/opencode/setup-harness.sh
```

---

## New Project Setup

### Step 0: Run the setup script in your target project

Run `opencode/setup-harness.sh` via any of the methods above.
After execution, the following files are created/copied:

- `AGENTS.md`: Project entry point (60-200 lines)
- `docs/`: Project definition, operations manual, various templates
- `.opencode/`: Harness body (instructions/ / skills/ / plugins/ / agents/)
- `.opencode/standards/`: yori reference documents (principles/ / architectures/)
- `opencode.json`: OpenCode configuration file
- `.env`, `.env.example`, `.editorconfig`
- `.git/hooks/pre-commit`: Secrets prevention hook

**Re-running is safe**: Project-specific files are not overwritten.
`.opencode/standards/` is always updated to the latest yori.

### Step 1: Open the project in OpenCode

Open the target project folder in OpenCode and tell the AI to start a new session.

### Step 2: Follow the AI's guidance

The AI will automatically guide you through project definition, architecture, and design setup. Answer the AI's questions about your project, and it will fill in `docs/project-definition.md`, `ARCHITECTURE.md`, `AGENTS.md`, and `.opencode/project-context.md` for you.

---

## Directory Structure

```
yori/
  opencode/
    setup-harness.sh       Setup script
    README.md              Setup guide (English)
    README.ja.md           Setup guide (Japanese)
    principles/            Universal principles (harness-engineering, security, code-quality, etc.)
    architectures/         Architecture patterns by project type
    decisions/             Decision records / ADRs
    snippets/              Template collection
      agents/              AGENTS.md template + subagent definitions
      .opencode/           Harness skeleton (instructions/ / skills/ / plugins/)
      docs/                Document templates
```

---

## Post-Setup Project Structure

```
target-project/
  AGENTS.md                 Entry point (60-200 lines)
  ARCHITECTURE.md           Architecture definition
  opencode.json             OpenCode configuration
  docs/
    project-definition.md   Project definition
    operations.md           Operations manual
    quality-scorecard.md    Quality scorecard
    build-log.md            Build log
    working/                Working directory
  .opencode/
    instructions/           Rule files (event-driven injection)
    plugins/                TypeScript plugins (automatic guardrails)
    skills/                 Project-scoped skills
    agents/                 Subagent definitions
    config/                 SSoT files (secret-patterns.json / skills.lock.yaml)
    standards/              yori copy (principles/ / architectures/)
      principles/.local/    Project-specific overrides
      architectures/.local/ Project-specific overrides
    adr-index.md            ADR Index (auto-generated by monthly diagnosis)
    handoff-artifact.md     Cross-session handoff
    project-context.md      Project context
    coding-conventions.md   Coding conventions
  .env                      Environment variables (human-only input)
  .env.example              Environment variable template (committed)
  .editorconfig             Cross-editor code style consistency
  .git/hooks/pre-commit     Secrets prevention hook
```

---

## Prerequisites

- **Bun**: Required to run TypeScript plugins in `.opencode/plugins/`.
  If not installed, follow the instructions at [bun.sh](https://bun.sh).
- **git**: Required for the setup script and pre-commit hooks.

## Minimum Setup

After yori setup is complete, open the project in OpenCode and start a session. The AI will automatically guide you through the setup:

1. `docs/project-definition.md` — Project purpose, requirements, and constraints
2. `ARCHITECTURE.md` — Tech stack and layer rules
3. `AGENTS.md` — Project name, commands, and prohibitions
4. `.opencode/project-context.md` — Lightweight context completion

The harness only starts functioning after these are complete.

---

## How to Grow the Harness

- **instructions/**: Add a rule file when AI makes the same point twice
- **skills/**: Formalize into a skill when the same task occurs 3+ times
- **Monthly diagnosis**: Just say "run monthly diagnosis" and it runs automatically
- **Production release**: Just say "I want to ship to production" and it guides you through preparation

See `.opencode/standards/principles/harness-engineering.md` for details.

---

## Update Rules

- After changing `opencode/principles/`, re-copy `.opencode/standards/` in each project
- Update `opencode/architectures/` based on project experience as needed
- Never delete `opencode/decisions/`
- Only include verified configuration files in `opencode/snippets/`