Skip to content

Commit c60b9bf

Browse files
codeaholicguycodeaholicguy
committed
docs: simplify READMEs
1 parent 14aacb0 commit c60b9bf

File tree

3 files changed

+75
-327
lines changed

3 files changed

+75
-327
lines changed

‎README.md‎

Lines changed: 40 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,63 @@
11
# AI DevKit
22

3-
**The standard for AI-assisted software development.**
3+
**The toolkit for AI-assisted software development.**
44

5-
AI DevKit is an open-source ecosystem designed to bridge the gap between human intent and AI execution. It provides a suite of tools that standardize how AI agents interact with codebases, manage context, and execute development workflows.
5+
AI DevKit helps AI coding agents work more effectively with your codebase. It provides structured workflows, persistent memory, and reusable skills — so agents follow the same engineering standards as senior developers.
66

77
[![npm version](https://img.shields.io/npm/v/ai-devkit.svg)](https://www.npmjs.com/package/ai-devkit)
88
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
99

10-
## Vision
11-
12-
The capabilities of AI coding agents are growing exponentially, but they often struggle with:
13-
1. **Context**: Losing track of broad project requirements and architectural decisions.
14-
2. **Consistency**: Generating code that doesn't follow project-specific patterns.
15-
3. **Process**: coding without a structured plan, leading to "spaghetti code".
16-
17-
**AI DevKit** solves this by enforcing a **Phase-Based Development** lifecycle—ensuring agents follow the same rigorous engineering
18-
standards as senior developers: Requirements → Design → Planning → Implementation → Testing.
19-
20-
## Packages
21-
22-
AI DevKit is a monorepo containing multiple specialized tools:
23-
24-
### [ai-devkit (CLI)](./packages/cli)
25-
The command-line interface that orchestrates the development lifecycle.
26-
- **Scaffold** structured documentation (Requirements, Design, Plan).
27-
- **Configure** environments for Cursor, Claude Code, and other agents.
28-
- **Manage** project state and development phases.
29-
30-
[**Explore the CLI Docs →**](./packages/cli/README.md)
31-
32-
### [@ai-devkit/memory](./packages/memory)
33-
A lightweight MCP-based memory service that gives agents persistent, searchable long-term memory.
34-
- **Store** architectural decisions and coding patterns.
35-
- **Search** documentation and knowledge using full-text search.
36-
- **Share** context across different agents and sessions.
37-
38-
[**Explore the Memory Docs →**](./packages/memory/README.md)
39-
4010
## Quick Start
4111

42-
To start using the core toolkit in your project instantly:
43-
4412
```bash
4513
npx ai-devkit init
4614
```
4715

48-
This will launch the interactive setup wizard to configure your project for AI-assisted development.
16+
This launches an interactive setup wizard that configures your project for AI-assisted development in under a minute.
4917

50-
## Contributing
18+
## What's Included
19+
20+
| Package | Description |
21+
|---------|-------------|
22+
| [**ai-devkit** (CLI)](./packages/cli) | Scaffold structured docs, configure AI environments, and manage development phases |
23+
| [**@ai-devkit/memory**](./packages/memory) | Give agents persistent, searchable long-term memory via MCP |
24+
25+
## Supported Agents
5126

52-
We welcome contributions! Whether you're building a new agent integration, adding a memory adapter, or improving our templates.
27+
| Agent | Status |
28+
|-------|--------|
29+
| [Claude Code](https://www.anthropic.com/claude-code) | ✅ Supported |
30+
| [GitHub Copilot](https://code.visualstudio.com/) | ✅ Supported |
31+
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ Supported |
32+
| [Cursor](https://cursor.sh/) | ✅ Supported |
33+
| [opencode](https://opencode.ai/) | ✅ Supported |
34+
| [Antigravity](https://antigravity.google/) | ✅ Supported |
35+
| [Codex CLI](https://github.com/openai/codex) | ✅ Supported |
36+
| [Windsurf](https://windsurf.com/) | 🚧 Testing |
37+
| [Kilo Code](https://github.com/Kilo-Org/kilocode) | 🚧 Testing |
38+
| [Roo Code](https://roocode.com/) | 🚧 Testing |
39+
| [Amp](https://ampcode.com/) | 🚧 Testing |
5340

54-
### Development Setup
41+
## Documentation
5542

56-
1. **Clone the repository**:
57-
```bash
58-
git clone https://github.com/Codeaholicguy/ai-devkit.git
59-
cd ai-devkit
60-
```
43+
📖 **Visit [ai-devkit.com](https://ai-devkit.com/docs/) for the full documentation**, including:
6144

62-
2. **Install dependencies**:
63-
```bash
64-
npm install
65-
```
45+
- Getting started guide
46+
- Phase-based development workflow
47+
- Memory system setup
48+
- Skill management
49+
- Agent configuration
6650

67-
3. **Build packages**:
68-
```bash
69-
npm run build
70-
```
51+
## Contributing
52+
53+
We welcome contributions! See the [Contributing Guide](./CONTRIBUTING.md) for details.
7154

72-
We use a monorepo structure. Ensure all changes are covered by tests before submitting a PR.
55+
```bash
56+
git clone https://github.com/Codeaholicguy/ai-devkit.git
57+
cd ai-devkit
58+
npm install
59+
npm run build
60+
```
7361

7462
## License
7563

‎packages/cli/README.md‎

Lines changed: 19 additions & 203 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,21 @@
1-
The official command-line interface for **AI DevKit**.
1+
# AI DevKit CLI
22

3-
This tool orchestrates the setup and management of AI-assisted development environments, ensuring your project is ready for agents like Cursor, Claude Code, Antigravity, and more.
3+
The command-line interface for **AI DevKit** — set up and manage AI-assisted development environments in your project.
44

55
[![npm version](https://img.shields.io/npm/v/ai-devkit.svg)](https://www.npmjs.com/package/ai-devkit)
66
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
77

88
## Features
99

10-
- 🎯 **Phase-based Development**: Structured templates for each stage of the software development lifecycle
11-
- 🤖 **AI Environment Setup**: Automatic configuration for Cursor and Claude Code
12-
- 📝 **Customizable Templates**: Markdown-based templates with YAML frontmatter
13-
- 🚀 **Interactive CLI**: User-friendly prompts with flag override support
14-
- ⚙️ **State Management**: Tracks initialized phases and configuration
10+
- 🎯 **Phase-based Development** — Structured templates for requirements, design, planning, implementation, testing, and more
11+
- 🤖 **AI Environment Setup** — One-command configuration for Cursor, Claude Code, Gemini CLI, and other agents
12+
- 🧠 **Skill Management** — Install and manage reusable AI skills from registries
13+
- 📝 **Customizable Templates** — Markdown-based templates with YAML frontmatter
1514

1615
## Installation
1716

1817
```bash
19-
# Using npx (no installation needed)
18+
# Run directly (no install needed)
2019
npx ai-devkit init
2120

2221
# Or install globally
@@ -25,221 +24,38 @@ npm install -g ai-devkit
2524

2625
## Quick Start
2726

28-
Initialize AI DevKit in your project:
29-
3027
```bash
31-
# Interactive mode (recommended)
28+
# Set up your project interactively
3229
ai-devkit init
3330
```
3431

3532
This will:
3633
1. Create a `.ai-devkit.json` configuration file
37-
2. Set up your AI development environment (Cursor/Claude Code)
34+
2. Set up your AI development environment (e.g., Cursor, Claude Code)
3835
3. Generate phase templates in `docs/ai/`
3936

40-
Detailed user guide can be found [here](https://ai-devkit.com/docs/).
41-
42-
## Available Phases
43-
44-
- **Requirements**: Problem understanding, requirements gathering, and success criteria
45-
- **Design**: System architecture, data models, and technical design (include mermaid diagrams for architecture/data flow)
46-
- **Planning**: Task breakdown, milestones, and project timeline
47-
- **Implementation**: Technical implementation notes and code guidelines
48-
- **Testing**: Testing strategy, test cases, and quality assurance
49-
- **Deployment**: Deployment process, infrastructure, and release procedures
50-
- **Monitoring**: Monitoring strategy, metrics, alerts, and observability
51-
52-
## Commands
53-
54-
### `ai-devkit init`
55-
56-
Initialize AI DevKit in your project.
57-
58-
**Options:**
59-
- `-e, --environment <env>`: Specify environment (cursor|claude|both)
60-
- `-a, --all`: Initialize all phases at once
61-
- `-p, --phases <phases>`: Comma-separated list of specific phases
37+
## Common Commands
6238

6339
```bash
64-
# Interactive mode
40+
# Initialize project
6541
ai-devkit init
6642

67-
# Initialize for Cursor with all phases
68-
ai-devkit init --environment cursor --all
69-
70-
# Initialize specific phases
71-
ai-devkit init --phases requirements,design,implementation
72-
```
73-
74-
### `ai-devkit phase [name]`
75-
76-
Add or update a specific phase template.
77-
78-
**Examples:**
79-
```bash
80-
# Interactive selection
81-
ai-devkit phase
82-
83-
# Add specific phase
43+
# Add a development phase
8444
ai-devkit phase requirements
85-
ai-devkit phase testing
86-
```
87-
88-
## Generated Structure
89-
90-
After initialization, your project will have:
9145

92-
```
93-
your-project/
94-
├── .ai-devkit.json # Configuration and state
95-
├── docs/
96-
│ └── ai/
97-
│ ├── requirements/
98-
│ │ └── README.md
99-
│ ├── design/
100-
│ │ └── README.md
101-
│ ├── planning/
102-
│ │ └── README.md
103-
│ ├── implementation/
104-
│ │ └── README.md
105-
│ ├── testing/
106-
│ │ └── README.md
107-
│ ├── deployment/
108-
│ │ └── README.md
109-
│ └── monitoring/
110-
│ └── README.md
111-
└── [Environment-specific files]
112-
```
46+
# Install a skill
47+
ai-devkit skill install <skill-name>
11348

114-
Supported Tools & Agents:
115-
| Agent | Support | Notes |
116-
|-----------------------------------------------------------|---------|---------------------------------------------------|
117-
| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | |
118-
| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | VSCode only |
119-
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | |
120-
| [Cursor](https://cursor.sh/) | ✅ | |
121-
| [opencode](https://opencode.ai/) | ✅ | |
122-
| [Antigravity](https://antigravity.google/) | ✅ | |
123-
| [Windsurf](https://windsurf.com/) | 🚧 | Testing |
124-
| [Kilo Code](https://github.com/Kilo-Org/kilocode) | 🚧 | Testing |
125-
| [Roo Code](https://roocode.com/) | 🚧 | Testing |
126-
| [Codex CLI](https://github.com/openai/codex) | ✅ | Only Global |
127-
| [Amp](https://ampcode.com/) | 🚧 | Testing |
128-
129-
Templates are designed to provide structure while remaining concise and AI-friendly.
130-
131-
## Workflow Examples
132-
133-
### Initial Project Setup
134-
135-
1. **Initialize your project:**
136-
```bash
137-
ai-devkit init
138-
```
139-
140-
2. **Start with requirements:**
141-
- Use slash command to start filling the requirement `/new-requerement`
142-
- Your AI assistant will help clarify and document requirements
143-
- Use slash command to review the requirement `/review-requirement`
144-
145-
3. **Design your system:**
146-
- Review `docs/ai/design/` and feature-specific files
147-
- Use slash command to review the design `/review-design`
148-
- Your AI assistant will help clarify and document design
149-
150-
4. **Plan your work:**
151-
- Review `docs/ai/planning/` and feature-specific plans
152-
- Clarify and document plan with AI assistant
153-
154-
5. **Implement with guidance:**
155-
- When the plan is ready, your AI assistant will help you implement the code
156-
- You can start the execution of the plan with the command `/execute-plan`
157-
- AI assistant will help you to review the code and update the implementation notes
158-
- After executing each task, you can check the implementation and compare it with the design with AI support by using the command `/check-implementation`
159-
- Once the implementation is good, you can review the code with AI support by using the command `/code-review`
160-
161-
6. **Test thoroughly:**
162-
- After implementation is done, you can start testing
163-
- Use `docs/ai/testing/` as your testing guide
164-
- Use slash command to start writing test `/writing-test`
165-
166-
7. **Deploy confidently:**
167-
- Follow deployment procedures in `docs/ai/deployment/`
168-
169-
8. **Monitor and iterate:**
170-
- Set up monitoring per `docs/ai/monitoring/`
171-
172-
## Use Cases
173-
174-
- **New Projects**: Scaffold complete development documentation
175-
- **Existing Projects**: Add structured documentation gradually
176-
- **Team Collaboration**: Share common development practices
177-
- **AI Pair Programming**: Provide context for AI assistants
178-
- **Knowledge Management**: Document decisions and patterns
179-
180-
## Best Practices
181-
182-
1. **Keep templates updated**: As your project evolves, update phase documentation
183-
2. **Reference across phases**: Link requirements to design, design to implementation
184-
3. **Use with AI assistants**: Templates are designed to work well with AI code assistants
185-
4. **Customize for your needs**: Templates are starting points, not rigid requirements
186-
5. **Track decisions**: Document architectural decisions and their rationale
187-
188-
## Configuration File
189-
190-
The `.ai-devkit.json` file tracks your setup:
191-
192-
```json
193-
{
194-
"version": "0.2.0",
195-
"environment": "cursor",
196-
"initializedPhases": ["requirements", "design", "planning"],
197-
"createdAt": "2025-10-14T...",
198-
"updatedAt": "2025-10-14T..."
199-
}
49+
# Store a memory
50+
ai-devkit memory store
20051
```
20152

202-
## Development
203-
204-
To work on the CLI package:
205-
206-
```bash
207-
# Clone the repository
208-
git clone <repository-url>
209-
cd ai-devkit
53+
## Documentation
21054

211-
# Install dependencies for the monorepo
212-
npm install
55+
📖 **For the full user guide, workflow examples, and best practices, visit:**
21356

214-
# Navigate to CLI package
215-
cd packages/cli
216-
217-
# Run in development mode
218-
npm run dev -- init
219-
220-
# Build
221-
npm run build
222-
223-
# Test locally
224-
npm link
225-
ai-devkit init
226-
```
227-
228-
## Contributing
229-
230-
Contributions are welcome! Please feel free to submit issues and pull requests.
57+
**[ai-devkit.com/docs](https://ai-devkit.com/docs/)**
23158

23259
## License
23360

23461
MIT
235-
236-
---
237-
238-
**Happy building with AI! 🚀**
239-
240-
## Quick Reference
241-
242-
| Quick links | Description |
243-
|-------------|-------------|
244-
| [CHANGELOG.md](CHANGELOG.md) | Recent changes and release notes |
245-

0 commit comments

Comments
 (0)