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

# 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

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.

# 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:

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

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

# 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.

Development

From this repo:

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