@ngocsangairvds/gc-kit 1.0.0

package/README.md

@@ -0,0 +1,35 @@
+# gc-kit
+
+A tiny CLI that copies a shared `.github/` folder into the current repository.
+
+## Usage
+
+```bash
+npx gc-kit init
+```
+
+### 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)
+
+Examples:
+
+```bash
+npx gc-kit init --dry-run
+npx gc-kit init --force
+npx gc-kit init --target /tmp/my-repo
+```
+
+## Development
+
+From this repo:
+
+```bash
+cd gc-kit
+npm test
+node ./bin/gc-kit.js init --dry-run
+```
+

package/bin/gc-kit.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Note: use a file URL so ESM resolution works reliably in more tooling environments.
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const initModuleUrl = pathToFileURL(path.join(__dirname, '..', 'src', 'commands', 'init.js')).href;
+const { initCommand } = await import(initModuleUrl);
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+async function main() {
+  if (!command || command === '-h' || command === '--help') {
+    printHelp(0);
+    return;
+  }
+
+  if (command === 'init') {
+    const exitCode = await initCommand(args.slice(1));
+    process.exitCode = exitCode;
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printHelp(1);
+}
+
+function printHelp(exitCode) {
+  const text = `gc-kit - copy a shared .github/ folder into your repo
+
+Usage:
+  npx gc-kit init [--force] [--dry-run] [--source <path>] [--target <path>]
+
+Commands:
+  init       Copy templates/.github -> <target>/.github
+
+Options:
+  --force    Overwrite existing files
+  --dry-run  Print what would happen without writing
+  --source   Source directory (defaults to packaged templates/.github)
+  --target   Target directory (defaults to current working directory)
+  -h, --help Show help
+`;
+  console.log(text);
+  process.exitCode = exitCode;
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ngocsangairvds/gc-kit",
+  "version": "1.0.0",
+  "description": "Copy a shared .github/ folder into the current repo.",
+  "license": "MIT",
+  "author": "Your Name <your.email@example.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/gc-kit.git"
+  },
+  "keywords": [
+    "github",
+    "cli",
+    "template",
+    "copy",
+    "agents",
+    "prompts"
+  ],
+  "type": "module",
+  "bin": {
+    "gc-kit": "./bin/gc-kit.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node ./scripts/smoke.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}
+

package/src/commands/init.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseInitArgs } from '../lib/parseArgs.js';
+import { copyDir } from '../lib/copyDir.js';
+
+export async function initCommand(argv) {
+  const opts = parseInitArgs(argv);
+
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+  const defaultSource = path.join(pkgRoot, 'templates', '.github');
+
+  const source = path.resolve(opts.source ?? defaultSource);
+  const targetRepoRoot = path.resolve(opts.target ?? process.cwd());
+  const target = path.join(targetRepoRoot, '.github');
+
+  const result = await copyDir({
+    sourceDir: source,
+    targetDir: target,
+    force: opts.force,
+    dryRun: opts.dryRun,
+    onLog: (line) => console.log(line)
+  });
+
+  if (result.errors.length > 0) {
+    console.error('\nErrors:');
+    for (const e of result.errors) console.error(`- ${e}`);
+    return 1;
+  }
+
+  if (opts.dryRun) {
+    console.log(`\nDry-run complete. ${result.copiedFiles} file(s) would be copied.`);
+  } else {
+    console.log(`\nInit complete. Copied ${result.copiedFiles} file(s) into ${target}.`);
+  }
+  return 0;
+}
+

package/src/lib/copyDir.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * @param {object} params
+ * @param {string} params.sourceDir
+ * @param {string} params.targetDir
+ * @param {boolean} params.force
+ * @param {boolean} params.dryRun
+ * @param {(line: string) => void} params.onLog
+ */
+export async function copyDir({ sourceDir, targetDir, force, dryRun, onLog }) {
+  /** @type {string[]} */
+  const errors = [];
+  let copiedFiles = 0;
+
+  const srcStat = await safeStat(sourceDir);
+  if (!srcStat?.isDirectory()) {
+    return {
+      copiedFiles,
+      errors: [`Source directory does not exist or is not a directory: ${sourceDir}`]
+    };
+  }
+
+  async function ensureDir(dirPath) {
+    if (dryRun) return;
+    await fs.mkdir(dirPath, { recursive: true });
+  }
+
+  async function copyEntry(srcPath, rel) {
+    const dstPath = path.join(targetDir, rel);
+
+    const st = await safeLstat(srcPath);
+    if (!st) {
+      errors.push(`Missing source entry: ${srcPath}`);
+      return;
+    }
+
+    if (st.isSymbolicLink()) {
+      // Avoid copying symlinks to prevent unexpected path escapes.
+      errors.push(`Refusing to copy symlink: ${path.join(sourceDir, rel)}`);
+      return;
+    }
+
+    if (st.isDirectory()) {
+      onLog(`[dir]  ${rel}`);
+      await ensureDir(dstPath);
+      const children = await fs.readdir(srcPath);
+      for (const name of children) {
+        await copyEntry(path.join(srcPath, name), path.join(rel, name));
+      }
+      return;
+    }
+
+    if (st.isFile()) {
+      const dstStat = await safeStat(dstPath);
+      if (dstStat && !force) {
+        onLog(`[skip] ${rel} (exists; use --force)`);
+        return;
+      }
+
+      onLog(`${dstStat ? '[ovr]' : '[cpy]'} ${rel}`);
+      if (!dryRun) {
+        await ensureDir(path.dirname(dstPath));
+        await fs.copyFile(srcPath, dstPath);
+        // best-effort: keep executable bit if present
+        try {
+          const mode = st.mode & 0o777;
+          await fs.chmod(dstPath, mode);
+        } catch {
+          // ignore
+        }
+      }
+      copiedFiles += 1;
+      return;
+    }
+
+    errors.push(`Unsupported file type: ${path.join(sourceDir, rel)}`);
+  }
+
+  await ensureDir(targetDir);
+  const top = await fs.readdir(sourceDir);
+  for (const name of top) {
+    await copyEntry(path.join(sourceDir, name), name);
+  }
+
+  return { copiedFiles, errors };
+}
+
+async function safeStat(p) {
+  try {
+    return await fs.stat(p);
+  } catch {
+    return null;
+  }
+}
+
+async function safeLstat(p) {
+  try {
+    return await fs.lstat(p);
+  } catch {
+    return null;
+  }
+}
+

package/src/lib/parseArgs.js

@@ -0,0 +1,44 @@
+export function parseInitArgs(argv) {
+  /** @type {{ force: boolean, dryRun: boolean, source?: string, target?: string }} */
+  const opts = { force: false, dryRun: false };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+
+    if (a === '--force') {
+      opts.force = true;
+      continue;
+    }
+
+    if (a === '--dry-run') {
+      opts.dryRun = true;
+      continue;
+    }
+
+    if (a === '--source') {
+      const v = argv[i + 1];
+      if (!v) throw new Error('--source requires a value');
+      opts.source = v;
+      i += 1;
+      continue;
+    }
+
+    if (a === '--target') {
+      const v = argv[i + 1];
+      if (!v) throw new Error('--target requires a value');
+      opts.target = v;
+      i += 1;
+      continue;
+    }
+
+    if (a === '-h' || a === '--help') {
+      // handled at top-level
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${a}`);
+  }
+
+  return opts;
+}
+

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

@@ -0,0 +1,38 @@
+---
+description: 'Document API Writer for this repo'
+tools: ['insert_edit_into_file', 'create_file', 'run_in_terminal', 'get_terminal_output', 'get_errors', 'show_content', 'open_file', 'list_dir', 'read_file', 'file_search', 'grep_search', 'validate_cves', 'run_subagent', 'semantic_search']
+---
+
+# DocumentApiWriter mode
+
+You are a documentation specialist for writing API documents in this repository.
+
+## Non-negotiable pre-flight (must happen BEFORE any writing)
+
+Before you write, generate, or edit **any** API documentation content, you MUST:
+1) Read `#file:.github/agents/agents-skills/document-api-writer/rule.md` **carefully and completely** (do not skip any section, including small notes and bullet points).
+2) Read `#file:.github/agents/agents-skills/document-api-writer/solution-design.md` **carefully and completely** (do not skip any section).
+3) Use those rules to guide what you produce.
+
+If any of these files can’t be found, you must stop and re-check the repo structure; do not proceed.
+
+## Template requirement (mandatory)
+
+- When producing API documentation, you MUST base the output on:
+  - `#file:.github/agents/agents-skills/document-api-writer/api-documentation-template.md`
+- The template structure must be followed fully; no section should be omitted unless the user explicitly asks to remove it.
+- Fill placeholders with project-appropriate content; if information is missing, explicitly mark it as “TBD” and list the questions needed.
+
+## 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/`
+- If the `documents/` folder does not exist, create it.
+- Use clear, kebab-case filenames (e.g., `api-<feature>-v1.md`).
+
+## Writing style & quality gates
+
+- Focus on **Why / What / High-level How**; avoid low-level implementation details.
+- Include decisions with options considered and trade-offs when relevant.
+- Ensure consistency and traceability across tables/diagrams/text.
+- Before finishing: re-check that the output maps to the template sections and that you followed the rules in `rule.md`.

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

@@ -0,0 +1,29 @@
+---
+description: Java development agent for this repo.
+tools: ['insert_edit_into_file', 'create_file', 'run_in_terminal', 'get_terminal_output', 'get_errors', 'open_file', 'list_dir', 'read_file', 'file_search', 'grep_search', 'validate_cves', 'run_subagent', 'semantic_search']
+---
+
+# JavaDev mode
+
+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.
+
+If you cannot find those files, you MUST stop and re-check the repo structure; do not proceed with edits until they are read.
+
+## Working style
+
+- Prefer small, safe changes that keep public APIs stable.
+- Always gather enough context (search + targeted file reads) before editing.
+- After edits: run `get_errors` on touched files, then run the fastest relevant build/test command (prefer Maven unit tests for this repo).
+- Be security-conscious: never print secrets; avoid network calls unless explicitly requested.
+
+## Quality gates before finishing
+
+- Build or tests are green (or failures are clearly explained and unrelated, with a minimal repro).
+- No new lint/type/compile errors are introduced.

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

@@ -0,0 +1,48 @@
+---
+description: 'API test-case writer & runner for this repo'
+tools: ['insert_edit_into_file', 'create_file', 'run_in_terminal', 'get_terminal_output', 'get_errors', 'show_content', 'open_file', 'list_dir', 'read_file', 'file_search', 'grep_search', 'validate_cves', 'run_subagent', 'semantic_search']
+---
+
+# TesterAPI mode
+
+You are a senior API tester agent for this repository.
+
+## Non-negotiable pre-flight (must happen BEFORE writing or testing)
+
+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/`
+   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`
+3) Use the test case template when generating any test-case document:
+   - `#file:.github/agents/agents-skills/test/API_TestCase_Template.md`
+
+If any required file cannot be found, stop and re-check the repo structure; do not proceed.
+
+## Test case generation (mandatory)
+
+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/`
+- 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/`.
+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.
+   - If auth/token/test data is required but not provided, mark the case as Blocked and clearly state what’s missing.
+3) Report results:
+   - A table of each test case with: expected vs actual, PASS/FAIL/BLOCKED.
+   - Identify inconsistencies between the API documentation and actual behavior.
+   - If the result indicates that a prior agent’s output is wrong (e.g., incorrect doc, wrong assumptions, wrong test steps), explicitly call that out: which agent/artifact is incorrect and why.
+
+## Output constraints
+
+- Do not invent endpoints, headers, tokens, or request/response schemas.
+- If the documentation is incomplete, clearly list the missing info and proceed only with what can be verified.

package/templates/.github/agents/agents-skills/dev/debugging_Rules_Senior_Developer.md

@@ -0,0 +1,116 @@
+# Debugging Rules & Practices (Senior Developer Guide)
+
+## Rule 0: Never Guess
+- Guessing is the slowest way to debug.
+- Always collect evidence before making changes.
+- Avoid random code changes without understanding the issue.
+
+## 1. Identify Bug Type Quickly
+Within the first minute, determine:
+- Does the bug happen always or intermittently?
+- Does it occur in production only?
+- Is it related to data, timing, concurrency, or environment?
+
+Correct classification reduces debugging time significantly.
+
+## 2. Reproduce the Bug
+- A bug that cannot be reproduced is not ready to be fixed.
+- Reproduce using the same:
+  - Input
+  - User
+  - Data
+  - Environment
+- If reproduction is not possible, rely on logs and traces instead of code changes.
+
+## 3. Find the Entry Point
+- Identify the exact API, job, event, or scheduler where the bug starts.
+- Begin debugging from:
+  - Controller
+  - Message consumer
+  - Scheduled job
+- Follow the execution flow step by step.
+
+## 4. Narrow the Scope
+- Reduce the search space aggressively.
+- Techniques:
+  - Temporarily comment out unrelated code
+  - Bypass branches
+  - Mock external services
+  - Fix input values
+- Goal: reduce thousands of lines to a small suspect area.
+
+## 5. Strategic Logging
+- Do not spam logs.
+- Log decision points and state changes.
+- Log:
+  - Input values
+  - State before and after changes
+  - Branches taken
+- Avoid logging inside large loops.
+
+## 6. Prefer Debugger Over Logs
+- Use breakpoints to inspect real runtime values.
+- Step through complex logic.
+- Watch variables and conditions closely.
+- Especially effective for:
+  - Complex conditionals
+  - Loops
+  - Unexpected branches
+
+## 7. Common Hard Bug Scenarios
+
+### 7.1 Production-only Bugs
+Common causes:
+- Different data
+- Timezone issues
+- Configuration mismatch
+- Concurrency
+Actions:
+- Compare configs
+- Inspect real production data
+- Enable temporary controlled logging
+
+### 7.2 Intermittent Bugs
+Usually caused by:
+- Race conditions
+- Missing transactions
+- Cache inconsistency
+Check:
+- Synchronization
+- Transaction boundaries
+- Cache eviction policies
+
+### 7.3 Logic Looks Correct but Fails
+Suspect:
+- Incorrect assumptions
+- Missing edge cases
+- Null or default values
+
+## 8. Debugging Checklist
+- [ ] Can the bug be reproduced?
+- [ ] Is the input correct?
+- [ ] Is the data as expected?
+- [ ] Which code branch is executed?
+- [ ] Are there side effects?
+- [ ] Is concurrency involved?
+- [ ] Is caching involved?
+- [ ] Are environment configs identical?
+
+## 9. After Fixing the Bug
+
+### 9.1 Add Tests
+- Create test cases that reproduce the bug.
+- Prevent regression.
+
+### 9.2 Root Cause Analysis
+- Identify why the bug existed.
+- Determine which rule or assumption failed.
+- Decide if refactoring is necessary.
+
+### 9.3 Improve the System
+- Add meaningful logs.
+- Strengthen validation.
+- Improve monitoring and alerts.
+
+## Core Debugging Mindset
+The bug is not stupid. The assumption is.

package/templates/.github/agents/agents-skills/dev/feature_Development_Reusing_Codebase_Rules.md

@@ -0,0 +1,62 @@
+# Feature Development Rules: Reusing Existing Codebase
+
+## 1. Mandatory Codebase Review
+- Always review existing code before implementing a new feature.
+- Do not start coding until similar logic has been searched and evaluated.
+- Skipping codebase review leads to duplicated logic and technical debt.
+
+## 2. Reasons to Read Existing Code
+- Avoid reinventing existing solutions.
+- Understand implicit business rules embedded in code.
+- Preserve architectural consistency.
+- Reuse or extend existing components properly.
+
+## 3. How a Senior Developer Reviews Codebase
+
+### Step 1: Identify Entry Points
+- Review related Controllers or APIs.
+- Understand request-to-response flow.
+
+### Step 2: Search for Similar Features
+- Search by domain keywords.
+- Check enums, statuses, and database tables.
+- Review services with similar responsibilities.
+
+### Step 3: Focused Reading
+Prioritize:
+- Business logic
+- Validation rules
+- Transaction boundaries
+- Integrations with external systems
+
+Skip:
+- Boilerplate code
+- Simple getters/setters
+- Trivial mappings
+
+### Step 4: Evaluate Reusability
+- Does the existing logic follow Single Responsibility Principle?
+- Can it be reused without increasing coupling?
+- Should it be refactored into a shared component?
+
+## 4. When NOT to Reuse Existing Code
+- Code is overly complex or unreadable.
+- Code has heavy side effects.
+- Code lacks tests and is risky to reuse.
+- Reuse would increase coupling or break abstraction.
+- Logic is coincidentally similar but belongs to a different domain.
+
+## 5. Team Rules for Feature Development
+- Every Pull Request must state:
+  - What code was reused, or
+  - Why reuse was not possible.
+- Copy-paste logic is strictly prohibited.
+- Refactoring should be discussed and agreed upon before reuse.
+
+## 6. Senior Developer Mindset
+- Write code for long-term maintainability, not just task completion.
+- Respect existing code but do not blindly depend on it.
+- Prefer consistency and clarity over clever implementations.
+
+## Core Principle
+Before writing new code, verify whether similar logic already exists.

package/templates/.github/agents/agents-skills/dev/java_Project_Development_Rules.md

@@ -0,0 +1,80 @@
+# Java Project Development Rules (Senior-Level)
+
+## 1. Coding Convention & Clean Code
+- Follow Java Code Convention and Google Java Style.
+- Class names: PascalCase
+- Method/variable names: camelCase
+- Constants: UPPER_SNAKE_CASE
+- Methods should not exceed 30–40 lines.
+- One method = one responsibility.
+- Avoid magic numbers; use constants.
+- Avoid deep nested conditionals (>3 levels).
+- Avoid boolean flags that make methods unclear.
+
+## 2. Architecture & Layered Design
+- Controller: handle HTTP request/response only.
+- Service: business logic only.
+- Repository: data access only.
+- Never expose Entity directly; use DTOs.
+- Controller must not access Repository directly.
+
+## 3. Performance & Scalability
+- Avoid database queries inside loops.
+- Fix N+1 query problems.
+- Always use pagination for list APIs.
+- Proper database indexing (WHERE, JOIN, ORDER BY).
+- Cache data that is read-heavy and rarely changes.
+- Avoid unnecessary object creation in hot paths.
+
+## 4. Exception Handling
+- Do not catch generic Exception.
+- Use domain-specific custom exceptions.
+- Use global exception handling.
+- Return clear error codes and messages.
+- Logging rules:
+  - ERROR: system failure
+  - WARN: abnormal business state
+  - INFO: main application flow
+
+## 5. Logging & Observability
+- Use SLF4J + Logback.
+- Include requestId / traceId in logs.
+- Never log sensitive data (passwords, tokens).
+- Avoid logging inside large loops.
+
+## 6. Transaction Management
+- @Transactional should be used at Service layer.
+- Avoid calling transactional methods within the same class.
+- Use readOnly transactions for read operations.
+- Understand propagation and isolation levels.
+
+## 7. Security Rules
+- Validate all input at system boundaries.
+- Never trust client-side data.
+- Do not expose stack traces to clients.
+- Do not decode JWT in Controllers.
+- Authorization should be handled via filters/interceptors.
+
+## 8. Testing & Quality Control
+- Business logic must have unit tests.
+- Avoid excessive mocking.
+- Cover:
+  - Happy path
+  - Edge cases
+  - Error cases
+- Enforce minimum test coverage (e.g. 70%).
+- No critical issues in static analysis tools.
+
+## 9. Dependency & Technical Debt Management
+- Do not add dependencies without clear justification.
+- Every dependency increases maintenance cost.
+- Address technical debt incrementally each sprint.
+
+## 10. Team & Code Review Rules
+- Keep pull requests small and focused.
+- Every PR must have a clear description.
+- Code review focuses on improvement, not blame.
+- Share knowledge through reviews.
+
+## Core Mindset
+Readable > Maintainable > Correct > Performant