npm package: @ngocsangairvds/gc-kit
Description: Test memory in mem0
Author: Your Name
Latest version: 1.0.5

# gc-kit

A tiny CLI that copies a shared `.github/` folder into the current repository, providing a complete AI-assisted development workflow with specialized agents for Java/Spring Boot projects.

## Quick Start

```bash
# Install into your project
cd your-project
npx @ngocsangairvds/gc-kit init

# Generate knowledge base
@create-knowledge

# Start developing
@JavaDev <your task>
```

## What is gc-kit?

gc-kit provides a structured workflow for AI-assisted development with 3 specialized agents:

1. **DocumentApiWriter** - Design API specifications first
2. **JavaDev** - Implement features based on specs and project standards
3. **TesterAPI** - Generate and execute comprehensive tests

### The Workflow

```
Design (@DocumentApiWriter) → Develop (@JavaDev) → Test (@TesterAPI)
```

**Key Concept**: Development reads from 2 knowledge sources:
- **`@project`** - Project-wide standards (HOW to build)
  - Coding conventions, architecture, tech stack, existing features
- **`@documents`** - Business requirements (WHAT to build)
  - API specs, validation rules, error codes, business logic

## Usage

```bash
npx @ngocsangairvds/gc-kit init
```

### Run Local MCP Memory Server (mem0)

Use this when you want multiple agents/tools to share one local project memory.

```bash
# Start MCP server over stdio, backed by local mem0
npx @ngocsangairvds/gc-kit mcp --project my-repo --scope project --agent default
```

The MCP server exposes these tools:
- `memory_upsert`
- `memory_search`
- `memory_list`
- `memory_get`
- `memory_delete`
- `memory_health`

Namespace format used for shared memory:
- `<project>:<scope>` (shared by all agents/tools)

Actor identity is still captured in each memory record metadata (`actor`) for traceability.

Defaults:
- `--mem0-base-url http://127.0.0.1:8011`
- `--scope project`
- `--agent unknown-agent`
- `--project` inferred from current folder name if omitted

### Options

- `--force` overwrite existing files under `.github/`
- `--dry-run` print what would be copied, without writing
- `--source <path>` copy from a custom `.github/` directory instead of the packaged template
- `--target <path>` copy into a different repo root (defaults to current directory)

MCP options:
- `--project <slug>` project namespace for shared memory
- `--scope <name>` scope namespace (default `project`)
- `--agent <name>` default actor id for memory writes
- `--mem0-base-url <url>` local mem0 endpoint (default `http://127.0.0.1:8011`)

**Note**: The `init` command copies `agents/` and `prompts/` folders, and creates empty `knowledge/` structure (project/, documents/, test-case/) without overwriting your existing knowledge files. The `--force` flag will NOT affect `knowledge/` folder.

Examples:

```bash
npx @ngocsangairvds/gc-kit init --dry-run
npx @ngocsangairvds/gc-kit init --force
npx @ngocsangairvds/gc-kit init --target /tmp/my-repo
```

## What's Included

This package includes a complete `.github/` folder structure with:

### Agents
- **JavaDev** - Java/Spring Boot development agent
- **DocumentApiWriter** - API documentation specialist
- **TesterAPI** - API testing agent

### Skills & Rules
- **Development Rules**: Debugging, feature development, Java best practices
- **Documentation Rules**: API documentation templates and guidelines
- **Testing Rules**: API testing strategies and test case templates

### Knowledge Templates
- `guidelines-template.md` - Code quality and conventions
- `product-template.md` - Product overview and features
- `structure-template.md` - Architecture and directory structure
- `tech-template.md` - Technologies and build commands

### Prompts
- `create-knowledge.prompt.md` - Generate knowledge files from templates

## How It Works

### 1. Initial Setup

```bash
npx @ngocsangairvds/gc-kit init
```

This creates the `.github/` structure in your project:

```
.github/
├── agents/              # Agent definitions and skills
├── knowledge/
│   ├── project/        # Project-wide knowledge (@project)
│   ├── documents/      # API specs & requirements (@documents)
│   └── test-case/      # Test cases
└── prompts/            # Reusable prompts
```

### 2. Generate Knowledge Base

```
@create-knowledge
```

Generates 4 knowledge files in `.github/knowledge/project/`:
- `guidelines.md` - Coding conventions from your codebase
- `structure.md` - Architecture and directory structure
- `tech.md` - Technologies, dependencies, build commands
- `product.md` - Product features and business context

### 3. Development Workflow

#### Phase 0: Design API

```
@DocumentApiWriter design user registration API with email validation
```

**Output**: `.github/knowledge/documents/api-user-registration-v1.md`
- Endpoint specifications
- Request/response schemas
- Validation rules
- Error codes

#### Phase 1: Implement Feature

```
@JavaDev implement user registration API based on the documentation
```

**JavaDev reads**:
- **From `@project`**: Coding standards, architecture, tech stack
- **From `@documents`**: API spec for user registration

**JavaDev does**:
1. Search for similar features in codebase
2. Reuse existing validation/patterns
3. Implement according to spec
4. Follow project conventions
5. Run tests
6. Update knowledge if needed

#### Phase 2: Test

```
@TesterAPI generate test cases for user registration API
@TesterAPI execute test cases for user registration
```

**Output**: Test cases in `.github/knowledge/test-case/tc-user-registration.md`
- Happy path, negative, boundary, security tests
- Execution results with PASS/FAIL
- Inconsistencies between doc and implementation

## Key Features

### 📚 Dual Knowledge System

**`@project`** (Always read):
- HOW to build: standards, architecture, tech
- Updated when project-wide changes occur

**`@documents`** (Feature-specific):
- WHAT to build: API specs, business requirements
- Updated when new features are added

### 🤖 Smart Development

- **Read before write**: Always reads project knowledge first
- **Reuse before create**: Searches for similar code
- **Spec-driven**: Implements according to API documentation
- **Auto-update**: Updates knowledge after changes

### ✅ Quality Assurance

- Design-first approach prevents misalignment
- Comprehensive test coverage (happy/negative/boundary/security)
- Automated test execution with curl
- Reports inconsistencies between docs and implementation

## Example: Complete Feature

```bash
# 1. Setup (one-time)
npx @ngocsangairvds/gc-kit init
@create-knowledge

# 2. Design API
@DocumentApiWriter design user registration API
# Creates: .github/knowledge/documents/api-user-registration-v1.md

# 3. Implement
@JavaDev implement user registration based on documentation
# Reads: @project (standards) + @documents (spec)
# Creates: Controller, Service, Repository
# Updates: @project/product.md (new feature)

# 4. Test
@TesterAPI generate test cases for user registration
@TesterAPI execute test cases
# Creates: .github/knowledge/test-case/tc-user-registration.md
# Reports: PASS/FAIL with actual vs expected
```

## Why gc-kit?

✅ **Consistent**: All code follows project standards
✅ **Documented**: API specs created before implementation
✅ **Tested**: Comprehensive test coverage
✅ **Maintainable**: Knowledge base stays in sync with code
✅ **Reusable**: Agents search and reuse existing code
✅ **Traceable**: Clear flow from design → code → tests

## Documentation

For detailed workflow and advanced usage, see [WORKFLOW.md](./WORKFLOW.md).

## Development

From this repo:

```bash
cd gc-kit
npm install
npm test
node ./bin/gc-kit.js init --dry-run
node ./bin/gc-kit.js mcp --project gc-kit --scope project --agent copilot
```