@ngocsangairvds/gc-kit 1.0.1 → 1.0.2

package/README.md

@@ -1,11 +1,45 @@
 # gc-kit
 
-A tiny CLI that copies a shared `.github/` folder into the current repository.
+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 gc-kit init
+npx @ngocsangairvds/gc-kit init
 ```
 
 ### Options
@@ -15,14 +49,178 @@ npx gc-kit init
 - `--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)
 
+**Note**: The `init` command copies `agents/` and `prompts/` folders, and creates empty `knowledge/` structure (project/, documents/, test-case/) without overwriting your existing knowledge files.
+
 Examples:
 
 ```bash
-npx gc-kit init --dry-run
-npx gc-kit init --force
-npx gc-kit init --target /tmp/my-repo
+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:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ngocsangairvds/gc-kit",
-  "version": "1.0.1",
-  "description": "Copy a shared .github/ folder into the current repo.",
+  "version": "1.0.2",
+  "description": "Refactor folder structure and add README.md for gc-kit",
   "license": "MIT",
   "author": "Your Name <your.email@example.com>",
   "repository": {

package/src/lib/copyDir.js

@@ -43,6 +43,17 @@ export async function copyDir({ sourceDir, targetDir, force, dryRun, onLog }) {
     }
 
     if (st.isDirectory()) {
+      // Skip knowledge/ directory contents to preserve user's existing knowledge
+      if (rel === 'knowledge') {
+        onLog(`[dir]  ${rel} (creating empty structure)`);
+        await ensureDir(dstPath);
+        // Create empty subdirectories
+        await ensureDir(path.join(dstPath, 'project'));
+        await ensureDir(path.join(dstPath, 'documents'));
+        await ensureDir(path.join(dstPath, 'test-case'));
+        return;
+      }
+
       onLog(`[dir]  ${rel}`);
       await ensureDir(dstPath);
       const children = await fs.readdir(srcPath);

package/templates/.github/agents/DocumentApiWriter.agent.md

@@ -26,7 +26,7 @@ If any of these files can’t be found, you must stop and re-check the repo stru
 ## Output location (mandatory)
 
 - When you create or update API documentation, you MUST place the document as a Markdown file under:
-  - `#file:.github/agents/agents-skills/documents/`
+  - `#file:.github/knowledge/documents/`
 - If the `documents/` folder does not exist, create it.
 - Use clear, kebab-case filenames (e.g., `api-<feature>-v1.md`).
 

package/templates/.github/agents/JavaDev.agent.md

@@ -10,9 +10,10 @@ You are a Java/Spring Boot programming agent working in this repository.
 ## Non-negotiable pre-flight (must happen BEFORE any code changes)
 
 Before you modify, create, or delete **any** code/config file, you MUST:
-1) Enumerate and read **all** markdown files under `.github/agents/agents-skills/dev/` (the `dev` folder), including `rule-base.md` and any other rule/prompt markdown files (including nested folders like `knowledge/`).
-2) Read them **carefully and completely** — do not skip **any** part, even small sections such as notes, subheadings, examples, footnotes, or single bullet points.
-3) Apply those rules when planning, editing, testing, and responding.
+1) Enumerate and read **all** markdown files under `.github/agents/agents-skills/dev/` (the `dev` folder), including `rule-base.md` and any other rule/prompt markdown files.
+2) Read **all** markdown files under `.github/knowledge/project/` (skip anything inside `.github/agents/template`).
+3) Read them **carefully and completely** — do not skip **any** part, even small sections such as notes, subheadings, examples, footnotes, or single bullet points.
+4) Apply those rules when planning, editing, testing, and responding.
 
 If you cannot find those files, you MUST stop and re-check the repo structure; do not proceed with edits until they are read.
 

package/templates/.github/agents/TesterAPI.agent.md

@@ -11,7 +11,7 @@ You are a senior API tester agent for this repository.
 
 Before you generate a test case document or run any API test, you MUST:
 1) Read the relevant API documentation file(s) referenced by the user under:
-   - `#file:.github/agents/agents-skills/documents/`
+   - `#file:.github/knowledge/documents/`
    Read them carefully and completely; do not skip any section.
 2) Read and follow the testing rules:
    - `#file:.github/agents/agents-skills/test/API_Testing_Rules.md`
@@ -26,13 +26,13 @@ When asked to create test cases for an API:
 - Generate the test case documentation in Markdown **based on** `API_TestCase_Template.md`.
 - Ensure coverage includes (as applicable): happy path, negative, boundary, security, and basic compatibility checks (per `API_Testing_Rules.md`).
 - Save the generated document under:
-  - `#file:.github/agents/agents-skills/test/test-case/`
+  - `#file:.github/knowledge/test-case/`
 - Use clear, kebab-case filenames, e.g. `tc-<api-name>-<endpoint>.md`.
 
 ## API execution using curl (mandatory when user asks to test an endpoint)
 
 When the user asks to test a specific API endpoint:
-1) Locate the corresponding test-case document in `#file:.github/agents/agents-skills/test/test-case/`.
+1) Locate the corresponding test-case document in `#file:.github/knowledge/test-case/`.
 2) Execute **all** test cases in that document using `curl` in the terminal.
    - Include headers/auth exactly as specified.
    - Capture HTTP status and response body.

package/templates/.github/agents/agents-skills/dev/rule-base.md

@@ -4,20 +4,21 @@
 - If the user only requests code changes/bug fixes/features and doesn’t mention documentation: **do not create any new `.md` files**.
 
 ## Rule 2 — Automatically update knowledge after code changes (when needed)
-- After you **create or modify code** according to the user’s request, **self-assess** whether the project documentation/knowledge needs to be updated.
-- If needed, **automatically update the corresponding files** in `#file:knowledge` (do not edit `knowledge/template`), for example:
-  - Architecture/folder/module changes → update `knowledge/structure.md`
-  - Tech stack/dependencies/build/run/config changes → update `knowledge/tech.md`
-  - Product behavior/features/API/business flows changes → update `knowledge/product.md`
-  - Dev conventions/coding standards/testing/release process changes → update `knowledge/guidelines.md`
+- After you **create or modify code** according to the user's request, **self-assess** whether the project documentation/knowledge needs to be updated.
+- If needed, **automatically update the corresponding files** in `#file:.github/knowledge/project` (do not edit `.github/agents/template`), for example:
+  - Architecture/folder/module changes → update `.github/knowledge/project/structure.md`
+  - Tech stack/dependencies/build/run/config changes → update `.github/knowledge/project/tech.md`
+  - Product behavior/features/API/business flows changes → update `.github/knowledge/project/product.md`
+  - Dev conventions/coding standards/testing/release process changes → update `.github/knowledge/project/guidelines.md`
 - Knowledge updates must:
   - Be concise and focused, reflecting **what actually changed**.
   - Avoid sensitive information (tokens/keys/credentials).
   - Only update when **truly necessary** (no “documentation for the sake of documentation”).
 
 ## Rule 3 — Read knowledge before coding
-- **Before writing any code**, always read and thoroughly understand all content in `#file:knowledge` (skip anything inside `knowledge/template`).
-- If the knowledge files **do not exist** (i.e., `knowledge/` is empty or the relevant `.md` files are missing):
-  - **Notify the user** immediately: _"The knowledge files in `knowledge/` do not exist."_
-  - Then **automatically generate** the knowledge files based on the templates found in `#file:template` (e.g., `structure.md`, `tech.md`, `product.md`, `guidelines.md`), filling in the content that reflects the current state of the project.
+- **Before writing any code**, always read and thoroughly understand all content in `#file:.github/knowledge/project`.
+- If the knowledge files **do not exist** (i.e., `.github/knowledge/project/` is empty or the relevant `.md` files are missing):
+  - **Notify the user** immediately: _"The knowledge files in `.github/knowledge/project/` do not exist."_
+  - Then **automatically generate** the knowledge files based on the templates found in `#file:.github/agents/template` (e.g., `structure.md`, `tech.md`, `product.md`, `guidelines.md`), filling in the content that reflects the current state of the project.
+  - Save the generated files into `.github/knowledge/project/`.
 - Do **not** proceed with coding until the knowledge content is available and has been read.

package/templates/.github/agents/agents-skills/test/API_Testing_Rules.md

@@ -63,4 +63,3 @@ When reading an API document, check:
 -   Define test data
 -   Define success/failure criteria
 
-------------------------------------------------------------------------

package/templates/.github/prompts/create-knowledge.prompt.md

@@ -1,30 +1,30 @@
 ---
-description: 'Tạo các file knowledge từ template'
+description: 'Generate knowledge files from templates'
 ---
 
-## Nhiệm vụ
-Hãy dựa vào các file template trong thư mục `#file:knowledge/template` để **tạo ra các file knowledge tương ứng** trong thư mục `#file:knowledge`.
+## Task
+Based on the template files in `#file:.github/agents/template`, **generate the corresponding knowledge files** into the folder `#file:.github/knowledge/project`.
 
 ## Input
-- Thư mục template: `#file:knowledge/template`
+- Template folder: `#file:.github/agents/template`
   - `guidelines-template.md`
   - `product-template.md`
   - `structure-template.md`
   - `tech-template.md`
 
 ## Output (Success criteria)
-Trong thư mục `#file:knowledge` phải có các file knowledge tương ứng (không nằm trong `template/`), ví dụ:
-- `#file:knowledge/guidelines.md`
-- `#file:knowledge/product.md`
-- `#file:knowledge/structure.md`
-- `#file:knowledge/tech.md`
+The following knowledge files must exist in `#file:.github/knowledge/project`:
+- `#file:.github/knowledge/project/guidelines.md`
+- `#file:.github/knowledge/project/product.md`
+- `#file:.github/knowledge/project/structure.md`
+- `#file:.github/knowledge/project/tech.md`
 
-## Yêu cầu
-- Nội dung mỗi file knowledge phải được tạo **dựa trên template tương ứng** (giữ cấu trúc/heading chính, điền nội dung phù hợp với repo hiện tại).
-- Không sửa các file trong `#file:knowledge/template`.
-- Nếu `#file:knowledge` đã có file đích, hãy **cập nhật/ghi đè** nội dung để đồng bộ với template mới nhất.
-- Văn bản viết bằng **tiếng Việt**, rõ ràng, có ví dụ ngắn khi cần.
+## Requirements
+- Each knowledge file must be generated **based on its corresponding template** (keep the main structure/headings, fill in content relevant to the current repo).
+- Do **not** modify any files in `#file:.github/agents/template`.
+- If a target file already exists in `#file:.github/knowledge/project`, **update/overwrite** it to sync with the latest template.
+- All content must be written in **English**, clearly and concisely, with short examples where helpful.
 
-## Ràng buộc
-- Không thêm template mới nếu không cần.
-- Không đưa thông tin bí mật (token, key, credential) vào các file knowledge.
+## Constraints
+- Do not add new templates unless explicitly required.
+- Do not include any sensitive information (tokens, keys, credentials) in the knowledge files.