Sync skills

.agents/skills/analyze/SKILL.md

@@ -8,7 +8,7 @@ license: MIT
 
 ## Purpose
 
-Reverse engineering documents capture **how a specific functionality actually works** in the current codebase and **keep that understanding in sync** as the system evolves. They serve as the project's living map — answering "how does this feature work from entry to exit?" for both human readers and agents. The analysis is either about a how-it-works or a module.
+ctest-Reverse engineering documents capture **how a specific functionality actually works** in the current codebase and **keep that understanding in sync** as the system evolves. They serve as the project's living map — answering "how does this feature work from entry to exit?" for both human readers and agents. The analysis is either about a how-it-works or a module.
 
 ### Unscoped Invocation
 

.gitignore

@@ -0,0 +1,37 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# codewiser base-content cache (three-way merge baseline)
+.codewiser-cache/
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store

README.md

@@ -14,7 +14,7 @@ Specs, plans, design options, architecture decisions — these are not paperwork
 
 ## How It Works
 
-A centralized `.agents/` directory and a universal `AGENTS.md` instruction file that every agent reads. Agents follow a **mode-tailored execution protocol**: depending on the selected mode (Prototype, Spec Driven, Rigid), they read relevant specs, create plans, explore options, and update artifacts before and after every code change.
+A centralized `.agents/` directory and a universal `AGENTS.md` instruction file that every agent reads. Agents follow a **mode-tailored execution protocol**: depending on the selected mode (Prototype, Spec Driven, or Rigid), they read relevant specs, create plans, explore options, and update artifacts before and after every code change.
 
 ```
 .agents/
@@ -45,24 +45,73 @@ A centralized `.agents/` directory and a universal `AGENTS.md` instruction file
 ## Quick Start
 
 ```bash
-# 1. Run the interactive setup script with a target directory
-./codewiser.sh ./my-project
+# Interactively set up codewiser in a target project directory
+bunx codewiser my-project
 
-# 2. Select your AI agents and development mode (Prototype, Spec Driven, or Rigid)
-#    The script downloads the relevant skills, spec templates, and creates
-#    agent-specific configs with symlinks to the shared `.agents/skills/` directory.
+# Or via npm (after publishing)
+npx codewiser my-project
 
-# 3. Start coding — agents read shared context from AGENTS.md (customized with your
-#    mode's execution protocol), load skills from `.agents/skills/`, and follow the
-#    tailored workflow defined by the selected mode.
+# Or if linked locally
+codewiser my-project
 ```
 
-On Windows (PowerShell):
+The CLI guides you through an interactive session:
 
-```powershell
-.\codewiser.ps1 .\my-project
+1. **Select AI agents** — Choose which coding agents to configure (OpenCode, Claude Code, Cursor, Antigravity, Kilo Code)
+2. **Configure mode** — Pick a development mode (Prototype, Spec Driven, or Rigid) — or select workflows in legacy mode
+3. **Download files** — Downloads shared skills, spec templates, and manifest from GitHub
+4. **Generate configs** — Creates agent-specific configuration files
+5. **Create symlinks** — Symlinks shared skills into each agent's private directory
+
+Use `← Back` options to navigate between steps. Press `Esc` at any time to exit.
+
+## Managing the Source Repo
+
+Codewiser syncs skills and specs from a GitHub repo's `codewiser.json` manifest. The source repo/branch is resolved from three tiers only: the project's `./codewiser.json` (if it sets `repo`/`branch`), then your user-profile `~/.codewiser.json` (if set), and finally the bundled default (`yallma3/codewiser` @ `main`). The fetched manifest's own `repo`/`branch` fields are informational and never override the effective source.
+
+From the root of a project that has a `codewiser.json`:
+
+```bash
+# Show the effective repo/branch and which source each value comes from
+codewiser repo
+
+# Point the manifest at a different repo/branch
+codewiser repo set owner/repo --branch main
+
+# Remove the overrides so the built-in defaults apply
+codewiser repo reset
+
+# Set a machine-wide (user profile) default instead of ./codewiser.json
+codewiser repo set owner/repo --branch main -g
+codewiser repo reset -g            # clear the user-wide default
+```
+
+`--repo` and `--branch` flags on the main command act as one-off overrides for a single run; they do not persist. Repo/branch resolution order is: CLI flag → `./codewiser.json` in the current directory (what `codewiser repo set` edits) → `~/.codewiser.json` in your user profile (what `codewiser repo set -g` edits) → bundled default (`yallma3/codewiser` @ `main`). A synced project's `./codewiser.json` (the merged manifest) always has `repo`/`branch`, so a project can be pointed at its own fork or a team fork with `codewiser repo set`.
+
+## Team Skill Sync
+
+The core goal of codewiser is letting the whole team share and evolve the same skills. Every synced project keeps a **merged `codewiser.json`** that lists each installed file with its **version and a SHA-256 content hash**. Two-way sync turns that ledger into a collaboration loop:
+
+```bash
+# Pull — fetch skills other members added or bumped upstream
+codewiser pull
+
+# Publish — open a pull request with YOUR locally edited skills
+codewiser publish
+
+# Both, in one interactive pass
+codewiser sync
 ```
 
+- **`codewiser pull`** compares the project's tracked versions/hashes against the upstream `codewiser.json`. It lists new files from the team (prompts to install), files with newer versions upstream (prompts to update), and warns about files you edited locally that also have newer upstream versions so you never silently lose your work.
+- **`codewiser publish`** detects locally edited skills by recomputing content hashes and comparing them to the ledger. It:
+
+  1. Checks upstream first — if another member already released a newer version of a skill you edited, it tells you and lets you **update to the latest or keep your version** before proceeding.
+  2. Lets you pick which modified skills to publish and **type a new version for each one** (that's what teammates see on their next `codewiser pull`).
+  3. Opens a pull request to the source repo. It uses the [GitHub CLI](https://cli.github.com) (`gh repo clone`, `git push`, `gh pr create`), falling back to a fork when you don't have write access. It updates the skill versions inside `codewiser.json` as part of the PR.
+
+  After a successful PR your local ledger is updated so the same edits aren't re-detected.
+
 ## Supported Agents
 
 | Agent | Config File | Integration |
@@ -85,23 +134,55 @@ The exact workflow depends on the selected mode (Prototype, Spec Driven, or Rigi
 
 ## Adding a New Skill
 
-Skills are shared across all agents. Create a file at `.agents/skills/<skill-name>/SKILL.md` with instructions for what the skill does. Then add it to the relevant workflow stage's `files` section in `manifest.json` with an initial version. The setup script symlinks this directory into each agent's private config so every agent can load it.
+Skills are shared across all agents. Create a file at `.agents/skills/<skill-name>/SKILL.md` with instructions for what the skill does. Then add it to the relevant workflow stage's `files` section in `codewiser.json` with an initial version. The setup script symlinks this directory into each agent's private config so every agent can load it.
 
 Example: the [git-worktrees skill](.agents/skills/shared/git-worktrees/SKILL.md) was added to teach agents how to isolate feature work using branches and worktrees during concurrent multi-agent development.
 
-## Setup Scripts
+## Requirements
 
-| Platform | Script | Source |
-|---|---|---|
-| Linux / macOS | `codewiser.sh` | Downloads `AGENTS.md`, skills, and specs from `https://github.com/yallma3/codewiser` |
-| Windows | `codewiser.ps1` | Same logic via PowerShell with `Invoke-WebRequest` |
+- **Bun** (recommended) or **Node.js 20.12+**
+- Git
 
-Both scripts use `manifest.json` to track artifact versions organized by development modes. During setup, you select which AI agents and which mode (**Prototype**, **Spec Driven**, or **Rigid**) to use. The selected mode determines which skills are downloaded and customizes `AGENTS.md` with the appropriate execution protocol.
+## Development
 
-## Requirements
+```bash
+# Clone and install
+git clone https://github.com/yallma3/codewiser.git
+cd codewiser
+bun install
 
-- Bash **or** PowerShell 5+
-- Git
+# Link globally (optional)
+bun link
+
+# Run directly
+bun start my-project
+
+# Or after linking
+codewiser my-project
+```
+
+## How the CLI Works
+
+The CLI uses [@clack/prompts](https://github.com/natemoo-re/clack) for interactive prompts and [meow](https://github.com/sindresorhus/meow) for CLI argument parsing. It downloads skills and specs from the [codewiser](https://github.com/yallma3/codewiser) repository based on a `codewiser.json` that tracks artifact versions organized by development modes.
+
+### Architecture
+
+- `src/index.ts` — Entry point, parses CLI arguments, resolves target directory, dispatches subcommands
+- `src/commands/init.ts` — State machine orchestrating the 5-step setup process
+- `src/commands/repo.ts` — `repo` subcommand: get/set/reset `repo`/`branch` in the manifest or user-profile (`-g`)
+- `src/commands/pull.ts` — `pull` subcommand: sync new/updated skills from the team
+- `src/commands/publish.ts` — `publish` subcommand: open a PR with locally edited skills (via gh CLI)
+- `src/commands/sync.ts` — `sync` subcommand: runs pull then publish
+- `src/utils/ui.ts` — Prompt wrappers with stdin resilience (@clack wrappers)
+- `src/utils/prompts.ts` — Typed prompt functions for agent/mode/workflow selection
+- `src/utils/download.ts` — HTTP download via `fetch()` + `Bun.write()`
+- `src/utils/manifest.ts` — Manifest parsing, version comparison, file flattening
+- `src/utils/hash.ts` — SHA-256 content hashing for local-edit detection
+- `src/utils/sync-files.ts` — Shared download/compare engine (versions + hashes) used by init and pull
+- `src/utils/remote.ts` — Remote manifest fetch and flattening
+- `src/utils/config.ts` — Merged project `codewiser.json` / `~/.codewiser.json` read/write, repo/branch resolution
+- `src/utils/generate-configs.ts` — Agent config file generation
+- `src/utils/symlinks.ts` — Symlink creation with admin retry and copy fallback
 
 ## License
 

.agents/manifest.json → codewiser.json

@@ -1,6 +1,6 @@
 {
-  "$schema": "manifest.json",
-  "description": "Version manifest for downloadable framework artifacts. Organized by modes. Used by codewiser.sh to detect and prompt for updates.",
+  "$schema": "codewiser.json",
+  "description": "Version manifest for downloadable framework artifacts. Organized by modes. Used by codewiser CLI to detect and prompt for updates.",
   "version": "3.0.0",
   "modes": {
     "prototype": {
@@ -143,5 +143,7 @@
         ".agents/specs/spec-index.json": "1.0.0"
       }
     }
-  }
+  },
+  "repo": "mostafamm44/codewiser",
+  "branch": "sync/codewiser.json"
 }