Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# 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
Comment on lines +13 to +16

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the log ignore globs.

_.log and the underscore-separated report... pattern use literal _ characters, so ordinary log and report files will not be ignored. Use wildcard syntax such as *.log and the intended report filename pattern.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.gitignore around lines 13 - 16, Update the log patterns in .gitignore:
replace the literal-underscore _.log entry with a wildcard pattern matching all
.log files, and revise the report pattern to use wildcards for each intended
numeric segment so standard report filenames are ignored.


# dotenv environment variable files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local

# caches
.eslintcache
.cache
*.tsbuildinfo

# IntelliJ based IDEs
.idea

# Finder (MacOS) folder config
.DS_Store
26 changes: 0 additions & 26 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,32 +8,6 @@ Project-specific scripts, technology choices, and setup instructions are documen
- `.agents/specs/` — What the agents are building (System & Product Architecture).
- `.agents/plans/` — How the agents will execute the current task (Short-term context).

## Spec-Driven Execution Protocol

All file modifications or code generation tasks MUST follow this lifecycle:

### Read Phase
1. Read `.agents/specs/product.md` to verify feature compliance.
2. Read `.agents/specs/system.md` to ensure architectural alignment.
3. Read `.agents/specs/ux.md` for UX and design system constraints.

### Spec Creation Sequence (when establishing a new feature)
1. **Bootstrap** — Initialize project context (`README.md`, `product.md`, `system.md`).
2. **Git Worktrees & Branch Management** — create an isolated feature branch or worktree before planning and spec changes.
3. **Create BRD** — Capture business requirements in `product_<domain>.md`.
4. **Create UX Specs** — Define design system, personas, and UX requirements in `ux.md`.
5. **Design DB** — Design relational schemas based on volumetric data; document in `system.md`.

### Execution (per task)
1. **Create Plan** — Break work into incremental, verifiable phases
(`.agents/plans/plan_YYMMDD_<name>.md`).
2. **Implement Plan** — Execute phases, verify gates, retry up to 5 times on
failure. On success, update `.agents/specs/spec-index.json` and
`.agents/specs/product.md` as needed.

### Core rule
If an implementation changes the system design, update the relevant spec files
first before writing production code.

## File Naming Conventions

Expand Down
70 changes: 48 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down Expand Up @@ -45,23 +45,25 @@ 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

Comment on lines +51 to 53

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== files =="
git ls-files | sed -n '1,120p'

echo "== README relevant =="
if [ -f README.md ]; then
  nl -ba README.md | sed -n '1,160p'
fi

echo "== download.ts =="
fd -a 'download\.ts$' . | while read -r f; do
  echo "--- $f"
  nl -ba "$f" | sed -n '1,220p'
done

echo "== package/scripts/imports =="
if [ -f package.json ]; then
  nl -ba package.json | sed -n '1,200p'
fi

echo "== search Bun/Cli usage =="
rg -n "Bun\.write|npx codewiser|node\s+|require\(|import \".*download|from \".*download|download" package.json src .github README.md 2>/dev/null || true

Repository: yallma3/codewiser

Length of output: 1306


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== README lines 1-160 =="
awk '{printf "%5d\t%s\n", NR, $0}' README.md | sed -n '1,160p'

echo "== package.json =="
awk '{printf "%5d\t%s\n", NR, $0}' package.json

echo "== src/utils/download.ts =="
awk '{printf "%5d\t%s\n", NR, $0}' src/utils/download.ts

echo "== CLI and download call sites =="
for f in src/commands/init.ts src/index.ts src/utils/*.ts package.json README.md; do
  echo "--- $f"
  awk '{printf "%5d\t%s\n", NR, $0}' "$f" | rg -n "download|npx|node|Bun\.write|fs\.|write" -C 3 || true
done

Repository: yallma3/codewiser

Length of output: 17762


Do not advertise Node.js/npx until the CLI avoids Bun-only APIs.

The README advertises npx codewiser and Node.js 18+, but src/utils/download.ts writes with Bun.write(), which makes the download step fail under Node.js and breaks the advertised npm path. Replace the download write path with Node-compatible APIs, or remove the Node.js/npx instructions and present Bun as required (while also removing the other Bun.file()/Bun.write() symlink path).

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 51 - 53, Update the README’s npm/npx and Node.js
guidance consistently with the CLI’s runtime support: either replace the
Bun-only APIs in the download and symlink paths, including Bun.write() and
Bun.file(), with Node-compatible implementations so the advertised path works,
or remove the Node.js/npx instructions and declare Bun required throughout.

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

## Supported Agents

Expand Down Expand Up @@ -89,19 +91,43 @@ Skills are shared across all agents. Create a file at `.agents/skills/<skill-nam

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 18+**
- 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-cli.git
cd codewiser-cli
bun install
Comment on lines +101 to +105

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Use the actual repository URL in the setup instructions.

The PR repository is yallma3/codewiser, but the documented command clones yallma3/codewiser-cli.git; following these instructions can fail or check out a different project.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 101 - 105, Update the README setup command to clone
the actual repository, yallma3/codewiser, instead of yallma3/codewiser-cli.git;
leave the subsequent directory change and installation commands consistent with
the corrected repository name.


- 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 `manifest.json` that tracks artifact versions organized by development modes.

### Architecture

- `src/index.ts` — Entry point, parses CLI arguments, resolves target directory
- `src/commands/init.ts` — State machine orchestrating the 5-step setup process
- `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/generate-configs.ts` — Agent config file generation
- `src/utils/symlinks.ts` — Symlink creation with admin retry and copy fallback

## License

Expand Down
47 changes: 47 additions & 0 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading