IssueOps-AI-Ready-Docs

Structure your project for AI-driven development without losing clarity, documentation rigor, and release discipline.

Practical usage

1. Fill out problem + requirements + use-cases first.
2. Then define domain + business rules.
3. Only then move to architecture + database + API.
4. UI comes after backend contracts are clear.
5. Build a release TODO list and transfer it to JSON to generate GitHub issues for release management.

Why this works with AI

Tools like ChatGPT, Claude, and autonomous agents work better when:

1. Context is explicit.
2. Rules are clear.
3. The domain is modeled.

This template turns your project into something AI can understand and evolve.

Docs folder structure

/docs
├── 1-problem.md
├── 2-requirements.md
├── 3-use-cases.md
├── 4-domain.md
├── 5-business-rules.md
├── 6-architecture.md
├── 7-database.md
├── 8-api.md
├── 9-ui.md
├── 10-changelogs.md
├── todo.md
└── github-issues-data-template.json

problem.md

• Problem description
• Target audience
• Why this matters
• Existing solutions and gaps

requirements.md

Functional

- User can create an account
- User can generate a report

Non-functional

- Response time < 300ms
- Authentication required
- Privacy/security compliance

use-cases.md

5-15 use cases can already define most of the system. Simple format:

[UC-01] Create project
Actor: User
Flow:
1. User submits name
2. System creates project
Result: Project is available

domain.md

Simple text or diagram. List entities and relationships:

User
- id
- email

Project
- id
- name
- user_id

User 1:N Project

business-rules.md

The real business logic belongs here:

- User can only access their own projects
- Project name must be unique per user
- Invoice sums all time entries

architecture.md

High-level technical decisions:

• Tech stack
• Type: Monolith / microservices
• Layers: Controller -> Service -> Repository -> DB
• Data flow:

Frontend -> API -> Service -> DB

• External integrations: payments, email, etc.

database.md

Based on domain + rules. Can include data types, indexes, and constraints:

users
- id
- email
- password

projects
- id
- name
- user_id

api.md

Define clear endpoints:

POST /projects
GET /projects
GET /projects/:id
DELETE /projects/:id

When needed, detail request/response:

POST /projects

Request:
{
  "name": "My project"
}

Response:
{
  "id": 1,
  "name": "My project"
}

Auth: Required

ui.md

Focus on UI behavior:

• Screen flows
• States: loading, error, empty
• Simple wireframes (optional) Example:

Screen: Project list
- List user projects
- "Create project" button
- Empty state: "No projects yet"

changelog.md

System evolution log:

[2026-04-07]
- Added project system
- Created POST /projects endpoint

[2026-04-08]
- Added JWT authentication

todo.md

Practical execution list:

- [ ] Create users table
- [ ] Implement login
- [ ] Create projects endpoint
- [ ] Create list screen

github-issues-data-template.json

Mirror of TODO list to import/create GitHub issues:

• structured backlog
• prioritization
• workflow integration

Minimal version (ultra lean)

/docs
  1-problem.md
  2-requirements.md
  3-use-cases.md
  4-domain.md
  5-business-rules.md
  6-architecture.md
  8-api.md

Running the GitHub issues script

Setup

1. Install GitHub CLI

   • macOS: brew install gh
   • Linux: Download from https://github.com/cli/cli/releases
   • Windows: choco install gh or install from GitHub releases

2. Authenticate

gh auth login
# Follow prompts (HTTPS + browser auth recommended)

3. Verify auth

gh auth status

Step 1: Test with dry run

Using Node.js

cd scripts
node create-github-issues.cjs {github_username}/{repo_name} --dry-run

Using Python

cd scripts
python3 create_github_issues.py {github_username}/{repo_name} --dry-run

Step 2: Review output

Dry run shows exactly what will be created with no changes applied.

Step 3: Create issues

Remove --dry-run to perform creation:

# Node.js
node create-github-issues.cjs {github_username}/{repo_name}

# Python
python3 create_github_issues.py {github_username}/{repo_name}