@robosoft/skillhub-cli 0.1.2 → 0.3.3

package/docs/skillhub-cli-logic.md

@@ -2,17 +2,48 @@
 
 ## Goal
 
-The CLI installs reusable project skills into any repository, similar to how package managers install dependencies.
-
-A SkillHub skill is a folder that contains:
+The SkillHub web app is the place where users create and maintain reusable project knowledge:
 
 ```txt
-skill.json
-SKILL.md
+skills/
 rules/
-templates/
-checklist/
-examples/
+domain/
+```
+
+The CLI runs inside an IDE/project and fetches those knowledge files into Cursor, Claude, or a generic `.ai` folder.
+
+## Knowledge Sections
+
+### Skills
+
+A skill is a reusable workflow/capability package.
+
+```txt
+skills/frontend/app/
+  skill.json
+  SKILL.md
+  templates/
+  examples/
+```
+
+### Rules
+
+A rule is a focused markdown file. All files use `.md`.
+
+```txt
+rules/frontend/antipattern.md
+rules/frontend/component-standards.md
+rules/backend/security.md
+```
+
+### Domain
+
+Domain knowledge stores product, platform, business, or architecture context.
+
+```txt
+domain/frontend/web-app.md
+domain/ott/video-cms.md
+domain/bfsi/compliance.md
 ```
 
 ## Commands
@@ -24,54 +55,74 @@ Creates project-level SkillHub files:
 ```txt
 skillhub.json
 skillhub.lock.json
-.ai/skills/
+.cursor/skills/
+.cursor/rules/
+.cursor/domain/
 ```
 
-### `skillhub install <skill[@version]>`
+Example:
+
+```bash
+skillhub init --target cursor --registry https://skillhub.your-company.com
+```
 
-Flow:
+### Short Fetch Commands
 
-1. Read `skillhub.json`.
-2. Resolve the registry from `--registry`, `SKILLHUB_REGISTRY`, or `skillhub.json`.
-3. Load the skill package from local registry or remote API.
-4. Validate `skill.json` and `SKILL.md`.
-5. Copy files into `.ai/skills/<skill-name>`.
-6. Update `skillhub.json`.
-7. Update `skillhub.lock.json` with version, source, checksum, and install path.
-8. Update adapters such as `AGENTS.md` and `.cursor/rules/skillhub.mdc`.
+```bash
+skillhub skill frontend/app
+skillhub rule frontend/antipattern
+skillhub domain frontend/web-app
+```
 
-### `skillhub sync`
+These are aliases for:
 
-Reinstalls all skills listed in `skillhub.json`.
+```bash
+skillhub attach skill frontend/app
+skillhub attach rule frontend/antipattern
+skillhub attach domain frontend/web-app
+```
 
-### `skillhub list`
+The first path segment is treated as a registry/category identifier. For example, `frontend/antipattern` is fetched from the frontend rule namespace, but it installs locally as `antipattern.md`.
 
-Reads `skillhub.lock.json` and prints installed skills.
+### `skillhub add`
 
-### `skillhub remove <skill>`
+With no arguments, restores/re-fetches all configured knowledge from `skillhub.json`. This is useful when local IDE files were deleted.
 
-Deletes the installed skill folder, removes it from config and lock, then refreshes adapters.
+```bash
+skillhub add
+```
+
+With arguments, it attaches one item, same as `install` or `attach`.
+
+### `skillhub sync`
+
+Re-fetches all configured knowledge from the registry/web app. `skillhub add` with no arguments uses the same restore behavior.
+
+### `skillhub list`
 
-### `skillhub create <skill>`
+Reads `skillhub.lock.json` and prints attached skills, rules, and domain files.
 
-Scaffolds a new local skill package into the registry.
+### `skillhub remove <section> <path>`
 
-### `skillhub validate <skill|path>`
+Removes attached knowledge and refreshes adapter files. You can remove by source path or local name.
 
-Checks whether a skill has valid metadata and required files.
+```bash
+skillhub remove rule frontend/antipattern
+skillhub remove rule antipattern
+```
 
 ### `skillhub generate <skill> <template> <name>`
 
-Generates project files from an installed skill template.
+Generates project files from an attached skill template.
 
 Example:
 
 ```bash
-skillhub install shadcn-crud-generator
-skillhub generate shadcn-crud-generator feature products --out src/features/products
+skillhub skill frontend/app
+skillhub generate frontend/app feature products --out src/features/products
 ```
 
-Template files can use variables like:
+Template files can use:
 
 ```txt
 {{name}}
@@ -81,25 +132,20 @@ Template files can use variables like:
 {{title}}
 ```
 
-## Local Registry Format
+## Remote Web App Contract
+
+Recommended endpoint:
 
 ```txt
-skillhub-registry/
-  nextjs-clean-architecture/
-    1.0.0/
-      skill.json
-      SKILL.md
-      rules/
-      checklist/
+GET /api/skillhub/:section/:path/:version
 ```
 
-## Remote Registry Contract
-
-The CLI supports remote registries with this endpoint pattern:
+Examples:
 
 ```txt
-GET /skills/:name/:version
-GET /skills/:name/latest
+GET /api/skillhub/rules/frontend/antipattern/latest
+GET /api/skillhub/skills/frontend/app/latest
+GET /api/skillhub/domain/frontend/web-app/latest
 ```
 
 Expected response:
@@ -107,62 +153,47 @@ Expected response:
 ```json
 {
   "manifest": {
-    "name": "nextjs-clean-architecture",
+    "name": "frontend/antipattern",
     "version": "1.0.0",
-    "entry": "SKILL.md"
+    "type": "rule",
+    "section": "rules",
+    "entry": "RULE.md"
   },
   "files": [
     {
-      "path": "SKILL.md",
-      "content": "# Next.js Clean Architecture"
+      "path": "RULE.md",
+      "content": "# Frontend Anti-Patterns\n..."
     }
   ]
 }
 ```
 
+Fallback registry endpoint:
+
+```txt
+GET /:section/:path/:version
+```
+
 ## Adapter Output
 
-The CLI can update these files:
+All generated adapter files use `.md`.
 
 ```txt
 AGENTS.md
-.cursor/rules/skillhub.mdc
+.cursor/rules/skillhub.md
 CLAUDE.md
+.claude/skillhub.md
 .github/copilot-instructions.md
 ```
 
-The enabled adapters are controlled in `skillhub.json`:
-
-```json
-{
-  "adapters": {
-    "agentsMd": true,
-    "cursorRules": true,
-    "claude": false,
-    "githubCopilot": false
-  }
-}
-```
-
-
-## Target folders
-
-SkillHub can install skill packages into different AI-tool folders instead of only `.ai/skills`.
-
-```bash
-skillhub init --target cursor
-skillhub init --target claude
-skillhub install nextjs-clean-architecture --target cursor
-skillhub target claude
-skillhub sync
-```
-
-Supported targets:
+## Target Folders
 
 ```txt
-ai      -> .ai/skills + AGENTS.md
-cursor  -> .cursor/skills + .cursor/rules/skillhub.mdc
-claude  -> .claude/skills + CLAUDE.md + .claude/skillhub.md
+ai      -> .ai/skills, .ai/rules, .ai/domain + AGENTS.md
+cursor  -> .cursor/skills, .cursor/rules, .cursor/domain + .cursor/rules/skillhub.md
+           source frontend/app installs as .cursor/skills/app
+           source frontend/antipattern installs as .cursor/rules/antipattern.md
+claude  -> .claude/skills, .claude/rules, .claude/domain + CLAUDE.md + .claude/skillhub.md
 ```
 
-The CLI also accepts `cloude` as an alias for `claude` to avoid failing on the common typo. Because apparently kindness can be implemented in 4 lines of code.
+The CLI also accepts `cloude` as an alias for `claude`, because apparently typo tolerance is now innovation.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@robosoft/skillhub-cli",
-  "version": "0.1.2",
-  "description": "Standalone SkillHub CLI for installing reusable AI/project skills into any codebase.",
+  "version": "0.3.3",
+  "description": "SkillHub CLI for fetching SkillHub web-app knowledge packages into IDE projects: skills, rules, and domain knowledge.",
   "type": "module",
   "bin": {
     "skillhub": "./bin/skillhub.mjs"
@@ -11,9 +11,9 @@
     "start": "node ./bin/skillhub.mjs",
     "test:help": "node ./bin/skillhub.mjs --help",
     "demo:init": "node ./bin/skillhub.mjs init",
-    "demo:install": "node ./bin/skillhub.mjs install nextjs-clean-architecture --registry ./skillhub-registry",
+    "demo:install": "node ./bin/skillhub.mjs skill frontend-app --registry ./skillhub-registry",
     "demo:list": "node ./bin/skillhub.mjs list",
-    "demo:validate": "node ./bin/skillhub.mjs validate nextjs-clean-architecture --registry ./skillhub-registry",
+    "demo:validate": "node ./bin/skillhub.mjs validate skill frontend-app --registry ./skillhub-registry",
     "prepublishOnly": "node ./bin/skillhub.mjs --help",
     "pack:dry-run": "npm pack --dry-run",
     "publish:public": "npm publish --access public"
@@ -37,7 +37,10 @@
     "cursor",
     "claude",
     "developer-tools",
-    "templates"
+    "templates",
+    "rules",
+    "domain-knowledge",
+    "agent-skills"
   ],
   "author": "Vikram Rajput",
   "license": "MIT",

package/skillhub-registry/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this template are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+### Added
+
+- `install.sh` — automated symlink installation script with smart detection of existing files (already-correct symlinks are left alone; foreign symlinks prompt before replace; real files are backed up to `<name>.backup-YYYYMMDD-HHMMSS` before being replaced).
+- `uninstall.sh` — companion script that removes only the symlinks created by `install.sh`. Real files and symlinks pointing to other templates are left untouched. Reports any `*.backup-*` files found in `~/.claude/` without auto-restoring them.
+- skills/react/SKILL.md: Service Layer Separation, expanded Forms, Accessibility, and Responsive Design sections (absorbed from team's Cursor rule)
+- rules/code-standards.md: Environment Variables and Secrets section
+- rules/code-standards.md: Logging section
+- domain/frontend-architecture.md: feature-based folder structure standard for tech-enabled projects
+
+### Changed
+
+- `README.md` Quick Install section now uses `./install.sh` instead of manual `ln -s` commands.
+- `docs/installation.md` reorganized to three methods: Method 1 (install script, recommended), Method 2 (manual symlink, advanced), Method 3 (direct copy). The Updating, Uninstalling, and Troubleshooting sections were updated to reference the new scripts.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+---
+
+## [0.1.0] - 2026-05-06
+
+Initial pilot release.
+
+### Added
+
+- `CLAUDE.md` entry point with `@import` auto-loading of the three always-on rule files.
+- `rules/general.md` — universal coding foundations (match codebase style, no hallucinated APIs, ask one clarifying question, prefer simplest solution, scope discipline).
+- `rules/code-standards.md` — concrete cross-language standards (function size, nesting depth, naming, magic values, error handling, side effects, duplication, comments, imports, file organization).
+- `rules/anti-patterns.md` — eleven cross-language anti-patterns with rationale and remediation.
+- `skills/api/SKILL.md` — universal API design and implementation standards.
+- `skills/build/SKILL.md` — structured implementation workflow for new code.
+- `skills/fast/SKILL.md` — fast-mode behavior for prototyping and rapid iteration.
+- `skills/feature-dev/SKILL.md` — end-to-end feature development workflow.
+- `skills/performance/SKILL.md` — performance optimization standards (measure first, then optimize).
+- `skills/react/SKILL.md` — React-specific component, hook, and rendering standards.
+- `skills/refactor/SKILL.md` — behavior-preserving restructuring workflow.
+- `skills/review/SKILL.md` — prioritized code critique workflow.
+- `skills/strict/SKILL.md` — strict-mode behavior for production-rigor work.
+- `skills/testing/SKILL.md` — test writing, mocking, and coverage standards.
+- `domain/api.md` — placeholder template for org-specific API conventions (envelope shape, auth, pagination, etc.).
+- `README.md` — overview, installation summary, structure reference, slash-command listing.
+- `docs/cost-hygiene.md` — pricing model explanation and the six habits for predictable token cost.
+- `docs/installation.md` — detailed install steps (symlink and direct-copy methods), per-project setup, verification, troubleshooting, updating, uninstalling, and Claude.ai fallback.
+
+### Notes
+
+- Initial pilot release, owned and maintained solo by Raj Shah.
+- Frontend/React-focused; other tech stacks (Python, Go, mobile, etc.) to follow in future releases.
+- Additional onboarding docs (`contributing.md`, `customization.md`, `exception-process.md`) referenced in `README.md` are not yet published and will arrive in a later release.
+- During pilot, rules and skills may change frequently; minor- and patch-version bumps are expected to be common.

package/skillhub-registry/CLAUDE.md

@@ -0,0 +1,108 @@
+# Claude Coding Template
+
+**Version:** 0.1.0 (pilot)
+**Last updated:** 2026-05-06
+**Owner:** [Your name / team]
+
+This is the entry point for the org's Claude coding rules. It is loaded automatically by Claude Code at the start of every session and tells Claude how to behave on coding tasks.
+
+---
+
+## How To Use This Template
+
+### For developers using this template
+1. Install per `docs/installation.md` (one-time setup).
+2. Work normally. The rules apply automatically.
+3. Use slash commands for specific workflows: `/build`, `/refactor`, `/review`, `/fast`, `/strict`.
+4. To request a rule change or exception, see `docs/exception-process.md`.
+
+### For Claude (instructions below this line)
+
+---
+
+## Operating Principles
+
+You are a senior software engineer assisting a developer at this organization. You follow the org's coding standards strictly but pragmatically.
+
+### Always-On Rules (auto-loaded every session)
+
+The following rule files are loaded automatically into every session via `@import`. They are non-negotiable defaults. Exceptions require explicit reasoning and should follow `docs/exception-process.md`.
+
+@rules/general.md
+@rules/code-standards.md
+@rules/anti-patterns.md
+
+**For developers:** Do not edit these files mid-session — it invalidates the cache. See `docs/cost-hygiene.md`.
+
+### Conditional Skills (load when relevant)
+
+These skills auto-load by topic match — Claude Code triggers them based on each skill's frontmatter description. You don't need to invoke them manually for them to work.
+
+- **`skills/api/SKILL.md`** — universal API design (REST, GraphQL, RPC, error shapes, pagination, etc.)
+- **`skills/performance/SKILL.md`** — performance optimization, profiling, bottleneck diagnosis
+- **`skills/react/SKILL.md`** — React, JSX/TSX, hooks, components, React-related libraries
+- **`skills/testing/SKILL.md`** — writing, modifying, or evaluating tests
+- **`domain/api.md`** — our org's specific API conventions (loaded alongside the API skill in our codebases)
+
+### Behavior Modes (user-invoked)
+
+The user may invoke a mode that adjusts your behavior:
+
+- **`/fast`** — prioritize speed over polish; minimal explanation; skip non-critical refactoring
+- **`/strict`** — apply rules with full rigor; flag every violation; prefer robust over quick
+
+If no mode is invoked, default to balanced behavior — neither rushed nor exhaustive.
+
+### Action Skills (invoke explicitly via slash commands)
+
+These skills produce structured workflows when invoked:
+
+- **`/build`** — `skills/build/SKILL.md` — structured implementation flow for new code
+- **`/refactor`** — `skills/refactor/SKILL.md` — restructure existing code without changing behavior
+- **`/review`** — `skills/review/SKILL.md` — critique code with prioritized findings
+- **`/feature-dev`** — `skills/feature-dev/SKILL.md` — end-to-end feature development across multiple phases
+
+### Behavior Modes (toggle Claude's rigor level)
+
+These skills adjust how strictly the rules apply:
+
+- **`/fast`** — `skills/fast/SKILL.md` — speed over polish, for prototyping only
+- **`/strict`** — `skills/strict/SKILL.md` — maximum rigor, for production code
+
+If no mode is invoked, default to balanced behavior — neither rushed nor exhaustive.
+
+---
+
+## Default Behavior
+
+When the user gives a coding task without specifying a mode or skill:
+
+1. **Read the relevant rule files** listed above.
+2. **Identify the task type** (build, refactor, review, explain).
+3. **Detect the domain** (React, API, general). Load the matching skill if any.
+4. **If anything is ambiguous**, ask one clarifying question before coding.
+5. **Apply the rules** while producing the output.
+6. **State any rule deviations explicitly** with a brief reason.
+
+---
+
+## Output Conventions
+
+- Default to code only — no preamble, no closing summary.
+- Add explanation only when (a) the user asks, (b) you made a non-obvious decision, or (c) you're uncertain.
+- For reviews and analyses, use structured sections (Critical / Improvements / Minor).
+- When you skip a rule, state which rule and why in one short line.
+
+---
+
+## When You're Uncertain
+
+State uncertainty explicitly. A confident wrong answer wastes more time than an honest "I don't know — can you confirm X?"
+
+Never invent APIs, libraries, function signatures, or syntax. If you're unsure something exists, ask.
+
+---
+
+## Versioning
+
+Changes to this template follow `CHANGELOG.md`. Breaking changes (rule removals, behavior shifts) bump the minor version. Additions and clarifications bump the patch version.