repo/
  README.md
  .gitignore
  .env.example

  docs/
    rules/
      index.md
      workflow.md
      testing.md
      security.md
      coding.md

  prompts/
    launch.md
    onboard.md
    think.md
    spike.md
    implement.md
    test.md
    review.md
    retrospect.md

  tasks/
    current.md
    20251228-example-task.md

  experiments/
    README.md
    20251228-example_spike.md

  test-data/
    README.md
    golden/
      README.md
      case01_input.json
      case01_expected.json

  src/
    core/
    adapters/
    app/

  tests/
    unit/
    integration/

# Secrets
.env

# Logs & temp
*.log
*.tmp
*.bak
*.swp

# OS
.DS_Store
Thumbs.db

# Language/runtime (adjust as needed)
__pycache__/
.pytest_cache/
node_modules/
dist/
build/
coverage/

# Copy to .env (DO NOT COMMIT .env)
# Example:
# API_BASE_URL=https://example.com
# API_TOKEN=replace_me

# AI-Driven Development (Prompt-Driven Development) Template

This template is for rapidly developing business improvements, automation, and small-scale toC in collaboration with AI, while ensuring "reproducibility," "capitalization," and "prevention of runaway" at minimal cost.

---

## Purpose
- Create quickly (utilizing AI)
- Make it robust (minimum safety devices)
- Ensure it can be fixed later (capitalize on prompts/investigations/expectations)
- Be tool-independent (usable with Web UI / IDE / CLI)

---

## Important Principles (Shortest)
- **Expectations (input → expected output) are confirmed by humans** (to prevent AI's circular references)
- **Commit prompts, task plans, and verification code** (essential for reproducibility)
- For unclear points, **conduct a Spike in `experiments/` before implementation**
- Rules should be **entry point + division** (keep `docs/rules/index.md` short)
- Done must include **asset updates** (adding golden cases/experiments/rules/README)

---

## Files to Always Provide to AI (Tool Independent)
Provide to AI at the start/resume:
1) docs/rules/index.md
2) tasks/current.md

*Note: Do not rely on automatic loading. Paste if using Web UI, or issue reference instructions if using IDE/CLI.*

---

## Workflow (With Safety Devices)
1) Plan & Approve
- AI generates/updates tasks/current.md (draft)
- Human confirms Acceptance (expectations) and marks Approval as APPROVED
- Implementation is prohibited until it becomes APPROVED

2) Spike (if necessary)
- Place reproducible/investigation code in experiments/
- Record results in experiments/README.md

3) Implement & Test
- Keep changes small (aim for 3-5 files)
- Use test frameworks by AI, with expectations confirmed by humans from test-data

4) Review & Commit
- Human checks git diff (stop unnecessary changes)
- Capitalize on meaningful history with Conventional Commits

5) Retrospect & Update (Done requirement)
- Implement at least one of:
  - Add golden test data
  - Add experiment (repro/investigation)
  - Update docs/rules or README
- Archive tasks/current.md into tasks/YYYYMMDD-*.md

# AI Working Agreement (Index)

## Read order (start/resume)
1) tasks/current.md
2) docs/rules/workflow.md
3) docs/rules/testing.md
4) docs/rules/security.md (if touching auth/data/secrets)
5) docs/rules/coding.md

## Hard rules (must follow)
- Do NOT code until tasks/current.md shows `Approval: APPROVED`.
- Human owns expected outputs (golden data). Do not invent expectations.
- If behavior is unclear, create a Spike under experiments/ before implementing.
- Never commit secrets (.env is forbidden). Use .env.example only.
- Touch only files related to the current task.
- Use Conventional Commits. Every commit should be meaningful.

# Workflow Rules (Small Project)

## Phases
1) Plan & Approve
- Generate/Update tasks/current.md
- Wait for human approval (APPROVED)

2) Spike (optional)
- Add experiments/ repro or investigation code
- Record result in experiments/README.md (1 line is enough)

3) Implement & Test
- Small changes per step (3-5 files, reasonable diff)
- Add/Update tests and/or test-data

4) Review & Commit
- Human checks git diff
- Conventional Commits

5) Retrospect & Update (Done requirement)
- Add at least one of:
  - new golden test-data case, or
  - new experiment/repro, or
  - rule update in docs/rules/ or README
- Archive tasks/current.md into tasks/YYYYMMDD-*.md

# Testing Rules

## Source of truth
- Truth = tests/ + test-data/
- Expected outputs (golden) are HUMAN-OWNED.

## Human-owned artifacts
- test-data/golden/*_expected.*  (or snapshots)
- tasks/current.md Acceptance section

## AI responsibilities
- Create test harness and assertions that compare actual vs human-provided expected.
- Do NOT modify expected outputs unless explicitly instructed by human.

## When adding a feature/fix
- Add/Update at least one golden test-data case.
- Cover boundaries and error cases (empty, null, malformed, large input).

## Anti-cheat rules
- Avoid writing tests that only mirror current implementation.
- Prefer black-box tests using golden input/output.

# Security & Privacy Rules (Small project baseline)

## Secrets
- Never commit .env. Only commit .env.example.
- No secrets in code, comments, tests, or logs.
- If a secret is found, STOP and warn the user.

## Data handling
- Do not add real customer/user data to repo.
- Use masked or synthetic datasets in test-data/ if needed.

## Token usage (optional tools)
- If using gh CLI, authentication is required:
  - local: `gh auth login`
  - CI/container: set `GH_TOKEN` and verify `gh auth status`
- Keep scopes minimal. Prefer read-only scopes unless needed.

## External tools / integrations
- Avoid introducing new external agents/tools without noting risks in tasks/current.md.

# Coding Rules

## Structure
- src/core: pure logic (no I/O)
- src/adapters: external I/O (API/DB/files)
- src/app: entrypoints (CLI/HTTP/job)

## Change scope
- Only edit files needed for current task.
- If broader refactor is needed, propose it in tasks/current.md and wait for approval.

## Style
- Keep functions small and single-responsibility.
- Prefer explicit error handling for external calls.

## Commit messages (Conventional Commits)
- feat: ...
- fix: ...
- refactor: ...
- test: ...
- docs: ...
- chore: ...

You are an assistant for creating development plans.
Please read the following and create or update tasks/current.md.

Read order:
1) docs/rules/index.md
2) README.md
3) existing tasks/current.md (if available)

Output requirements:
- tasks/current.md should be a "plan document for human approval."
- Place Goal / Non-goals / Acceptance (Human-owned) at the top.
- Divide the Plan into "granularity that AI can handle in one context":
  - About 3-5 files to change
  - If the diff is large, divide it
- If there are unclear points, include a Spike in the Plan, assuming it will be placed in experiments/ before proceeding.
- Approval must be set to `WAITING` (implementation is prohibited until the human changes it to APPROVED).
- Expected outputs (expected) are confirmed by humans, so do not create them arbitrarily; leave a space for humans to fill in.

Resuming work. Please execute the following:

1) Read docs/rules/index.md and tasks/current.md, and summarize the current situation.
2) Next, select one checklist item from tasks/current.md (ensure Approval is APPROVED).
3) Briefly present "impact file candidates," "implementation policy," and "verification method" for that one item.
4) Do not write code yet (only plan here).

Please summarize the implementation policy for the following subtask before implementation.

- Responsibility to change (somewhere in core/adapters/app)
- Exceptions and boundary conditions
- If dependencies are unclear, is a Spike necessary?
- What should be added in test data (golden) (expectations are to be written by humans).

Conducting a Spike (investigation).

- Organize investigation procedures and expected observation results, assuming you will create experiments/YYYYMMDD-<topic>.
- Write down what needs to be understood to proceed to the main implementation (Go/No-Go conditions).
- Also provide a draft for recording results in experiments/README.md.

Entering implementation. Rules:

- Only implement within the APPROVED range of tasks/current.md
- Keep changed files to a minimum (aim for 3-5 files)
- Do not change expected values (test-data's expected) until confirmed by humans
- Encapsulate external I/O in adapters
- After implementation, provide "how to verify (commands/observation points)."

Preparing tests.

- Create test code on the tests/ side (comparison framework)
- Structure it to read from test-data/golden's input/expected
- Treat the contents of expected as placeholders since humans will prepare them
- Propose additional boundary/abnormal cases (but do not create expectations).

Preparing for review.

- List the changed files.
- Self-check for any unexpected changes.
- Present a table showing compliance with specifications (Acceptance).
- Propose commit messages in Conventional Commits format.

Reflect and capitalize.

- What went well / what did not
- Rules to be followed in the next similar task (suggest where to add in docs/rules)
- Additional golden test-data cases or proposals for reproducible code in experiments
- Propose a rename plan to save tasks/current.md as tasks/YYYYMMDD-<short>.md

# Goal
(Human writes) What this task aims to achieve in 1-3 lines.

# Non-goals
(Human writes) What will not be done this time. Prevents scope creep.

# Acceptance (Human-owned)
*Expectations are confirmed by humans. AI does not create them.*
- Case01: input = test-data/golden/case01_input.json -> expected = test-data/golden/case01_expected.json
- Case02: input = ... -> expected = ...

# Plan (AI drafts, Human approves)
- [ ] Spike: (if necessary) Add dependency/existing code behavior confirmation to experiments/
- [ ] Implement: Change src/... (target files:)
- [ ] Test: Add tests/... (golden comparison)
- [ ] Review: Create summary of changes and proposed commit messages
- [ ] Retrospect: Add golden cases or update rules or add experiments (Done condition)

# Notes
- Constraints, pitfalls, notes

# Approval
Status: WAITING
Approved by:
Approved at:

# experiments/

Place reproducible code for confirming library behaviors, reproducing bugs, and checking boundary conditions.
This is a "living document." Do not discard it (it is subject to commit).

## Index
- 20251228-example_spike.md: Example

# Spike: Example

Purpose:
- Confirm the input format of Library X

Go/No-Go:
- No exceptions with Input A
- Output in this format with Input B (observation)

Results:
- (To be added after execution)

# test-data/

Place "expected values" confirmed by humans.
To prevent AI's circular references, expected values are confirmed by human review.

- golden/: Black-box input/expected output pairs

# golden test-data

Naming:
- caseNN_input.*
- caseNN_expected.*

Operation:
- Expected values are confirmed by humans (AI does not create them arbitrarily)
- Add boundary/abnormal cases.

{
  "example": "input"
}

{
  "example": "expected"
}