@maggit/claude-workspace 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raquel Hernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# Claude Workspace
+
+**Dotfiles for Claude** — scaffold a structured AI workspace into any project with one command.
+
+Claude Workspace sets up everything you need to work effectively with Claude: a Markdown knowledge vault, curated skills (promptable playbooks), document templates, and a ready-to-use `CLAUDE.example.md`. It's idempotent, profile-based, and designed for teams and solo builders alike.
+
+---
+
+## Quick Start
+
+```bash
+npx @maggit/claude-workspace init
+```
+
+That's it. You'll be prompted to pick a profile and vault name, and your workspace is ready.
+
+For non-interactive setup:
+
+```bash
+npx @maggit/claude-workspace init --profile engineering-exec --yes
+```
+
+## What You Get
+
+```
+your-project/
+├── CLAUDE.example.md              # Workspace instructions for Claude (rename to CLAUDE.md)
+├── .claude/
+│   ├── config.json                # Workspace configuration
+│   ├── skills/                    # Promptable mini-playbooks
+│   │   ├── prd/SKILL.md
+│   │   ├── eng-spec/SKILL.md
+│   │   └── ...
+│   ├── templates/                 # Document templates
+│   │   ├── PRD_TEMPLATE.md
+│   │   ├── ENG_SPEC_TEMPLATE.md
+│   │   └── ...
+│   ├── snippets/                  # Your snippets (empty)
+│   ├── logs/                      # Your logs (empty)
+│   └── profiles/
+│       └── active.json            # Tracks installed files for idempotency
+└── ContextDB/                     # Markdown knowledge vault
+    ├── README.md
+    ├── _index.md
+    ├── 00_inbox/
+    ├── 01_specs/
+    ├── 02_architecture/
+    ├── 03_decisions/
+    ├── 04_knowledge/
+    ├── 05_prompts/
+    ├── 06_agents/
+    ├── 07_diagrams/
+    └── 08_todos/
+```
+
+## Setting Up CLAUDE.md
+
+Claude Workspace never touches your `CLAUDE.md`. It writes `CLAUDE.example.md` so you stay in control.
+
+**New project** — rename it:
+
+```bash
+mv CLAUDE.example.md CLAUDE.md
+```
+
+**Existing project with a CLAUDE.md** — open `CLAUDE.example.md` and merge the parts you want (vault references, skill instructions, conventions) into your existing file.
+
+## Profiles
+
+Profiles determine which skills and templates get installed:
+
+| Profile | Skills | Best for |
+|---------|--------|----------|
+| **default** | All 9 skills, all 5 templates | Full workspace — everything included |
+| **engineering-exec** | PRD, eng-spec, requirements, todo, release-plan | Engineering leads and architects |
+| **indie-maker** | PRD, todo, summary, release-plan | Solo builders shipping fast |
+| **marketing** | PRD, SEO brief, landing page copy, summary, meeting notes | Content and growth teams |
+
+```bash
+# Use a specific profile
+cws init --profile marketing
+```
+
+## Skills
+
+Skills are Markdown playbooks that teach Claude how to produce specific document types. They live in `.claude/skills/` and are referenced by name:
+
+| Skill | Produces |
+|-------|----------|
+| `prd.md` | Product Requirements Documents |
+| `eng-spec.md` | Engineering Specifications |
+| `requirements.md` | Structured Requirements |
+| `todo.md` | Task Breakdowns |
+| `summary.md` | Summaries and Recaps |
+| `meeting-notes.md` | Meeting Notes |
+| `release-plan.md` | Release Plans |
+| `seo-brief.md` | SEO Content Briefs |
+| `landing-page-copy.md` | Landing Page Copy |
+
+## Commands
+
+### `init`
+
+Scaffold a workspace. Safe to run multiple times — existing files are preserved, unchanged managed files are skipped.
+
+```bash
+cws init [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-d, --dir <path>` | Target directory | `.` |
+| `-p, --profile <name>` | Profile | `default` |
+| `--vault <name>` | Vault folder name | `ContextDB` |
+| `--force` | Overwrite user-modified managed files (backs up first) | `false` |
+| `--dry-run` | Preview what would happen | `false` |
+| `-y, --yes` | Skip prompts, use defaults | `false` |
+
+### `doctor`
+
+Check that your workspace is healthy:
+
+```bash
+cws doctor
+```
+
+```
+PASS  .claude/ directory exists
+PASS  config.json valid (profile: default)
+PASS  All 9 skill files present
+PASS  All 5 template files present
+PASS  Vault directory exists: ContextDB/
+PASS  All 9 vault subfolders present
+PASS  CLAUDE.md present
+```
+
+### `add-skill`
+
+Install a single skill without running a full `init`:
+
+```bash
+cws add-skill prd
+cws add-skill --list
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-d, --dir <path>` | Target directory | `.` |
+| `--force` | Overwrite existing skill (backs up first) | `false` |
+| `--dry-run` | Preview what would happen | `false` |
+| `-l, --list` | List all available skills | `false` |
+
+### `print-claude-md`
+
+Preview the CLAUDE.md content for a profile without writing any files:
+
+```bash
+cws print-claude-md --profile indie-maker
+```
+
+## Installation
+
+### npx (recommended)
+
+```bash
+npx @maggit/claude-workspace init
+```
+
+### Global install
+
+```bash
+npm install -g @maggit/claude-workspace
+cws init
+```
+
+### Clone and run
+
+```bash
+git clone https://github.com/raquelhernandez/claude-workstation.git
+cd claude-workstation
+pnpm install && pnpm build
+node packages/cli/dist/bin.js init --dir ~/my-project
+```
+
+## Idempotency
+
+Running `init` again is always safe:
+
+- **Managed files** (skills, templates) are tracked by SHA-256 hash. If the file hasn't changed, it's skipped.
+- **User-modified files** are detected and preserved. Use `--force` to overwrite (a `.bak` backup is created first).
+- **Unmanaged files** (existing skills not tracked by the CLI) are skipped with a warning. Use `--force` to overwrite, or delete them and re-run.
+- **CLAUDE.example.md** is regenerated on each run — it's the reference file, not your working file.
+- **Vault folders** are created if missing, never deleted.
+
+## Customization
+
+See [docs/customization.md](docs/customization.md) for:
+
+- Creating custom profiles
+- Writing new skills
+- Adding templates
+- Changing vault structure
+- Custom CLAUDE.md templates
+
+## ContextLoom
+
+Claude Workspace is designed to work with [ContextLoom](https://contextloom.app), a Markdown editor for managing project context. The vault taxonomy and file conventions are fully compatible. See [docs/contextloom.md](docs/contextloom.md) for details.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
+
+- Setting up the development environment
+- Adding skills, templates, and profiles
+- Code style and testing expectations
+- Pull request process
+
+## Development
+
+```bash
+pnpm install        # Install dependencies
+pnpm build          # Build (copies assets + compiles TypeScript)
+pnpm test           # Run all tests
+```
+
+## License
+
+[MIT](LICENSE)

package/assets/claude-md/default.md

@@ -0,0 +1,34 @@
+# Project Workspace
+
+This workspace is managed by [claude-workstation](https://github.com/raquelhernandez/claude-workstation).
+
+## Vault
+
+All project context lives in `{{vaultPath}}/`. This is a structured Markdown vault designed for both humans and AI tools.
+
+### Folder Taxonomy
+
+{{folderList}}
+
+### Naming Conventions
+
+{{namingConvention}}
+
+## Skills
+
+Skills are promptable mini-playbooks installed in `.claude/skills/`. Use them by referencing the skill name when asking Claude to produce a specific document type.
+
+{{skillInstructions}}
+
+## Templates
+
+Document templates are available in `.claude/templates/`. Copy a template to start a new document with the right structure.
+
+## Working Agreements
+
+- Always read relevant context from the vault before starting work
+- Write new context documents back to the appropriate vault folder
+- Use the installed skills when producing standard document types
+- Follow the naming conventions above for new files
+- Keep documents small and composable — one topic per file
+- Use relative Markdown links between documents

package/assets/claude-md/engineering-exec.md

@@ -0,0 +1,34 @@
+# Engineering Workspace
+
+This workspace is managed by [claude-workstation](https://github.com/raquelhernandez/claude-workstation) with the **engineering-exec** profile.
+
+## Vault
+
+All project context lives in `{{vaultPath}}/`. This is a structured Markdown vault for specs, decisions, and engineering planning.
+
+### Folder Taxonomy
+
+{{folderList}}
+
+### Naming Conventions
+
+{{namingConvention}}
+
+## Skills
+
+Skills are promptable mini-playbooks installed in `.claude/skills/`. Use them for producing engineering documents.
+
+{{skillInstructions}}
+
+## Templates
+
+Document templates are available in `.claude/templates/`. Use these for consistent spec and decision formatting.
+
+## Working Agreements
+
+- Start with requirements and specs before implementation
+- Record architectural decisions in the decisions folder
+- Break work into tasks with clear acceptance criteria
+- Write release plans before shipping
+- Keep specs and requirements up to date as decisions evolve
+- Review the project index weekly

package/assets/claude-md/indie-maker.md

@@ -0,0 +1,33 @@
+# Maker Workspace
+
+This workspace is managed by [claude-workstation](https://github.com/raquelhernandez/claude-workstation) with the **indie-maker** profile.
+
+## Vault
+
+All project context lives in `{{vaultPath}}/`. A lightweight vault for fast-moving solo projects.
+
+### Folder Taxonomy
+
+{{folderList}}
+
+### Naming Conventions
+
+{{namingConvention}}
+
+## Skills
+
+Skills are promptable mini-playbooks installed in `.claude/skills/`.
+
+{{skillInstructions}}
+
+## Templates
+
+Document templates are available in `.claude/templates/`. Use these to quickly scaffold new documents.
+
+## Working Agreements
+
+- Keep planning lightweight — just enough structure to stay on track
+- Write a quick PRD before building anything significant
+- Maintain a running todo list for the current iteration
+- Summarize what you shipped after each work session
+- Plan releases even for solo projects — it clarifies scope

package/assets/claude-md/marketing.md

@@ -0,0 +1,33 @@
+# Marketing Workspace
+
+This workspace is managed by [claude-workstation](https://github.com/raquelhernandez/claude-workstation) with the **marketing** profile.
+
+## Vault
+
+All project context lives in `{{vaultPath}}/`. A structured vault for content planning and marketing materials.
+
+### Folder Taxonomy
+
+{{folderList}}
+
+### Naming Conventions
+
+{{namingConvention}}
+
+## Skills
+
+Skills are promptable mini-playbooks installed in `.claude/skills/`.
+
+{{skillInstructions}}
+
+## Templates
+
+Document templates are available in `.claude/templates/`. Use these for consistent content planning.
+
+## Working Agreements
+
+- Research SEO keywords before writing content
+- Create briefs before drafting landing pages or articles
+- Document meeting outcomes and action items
+- Summarize campaign results and learnings
+- Keep the project index current with all active initiatives

package/assets/profiles/default.json

@@ -0,0 +1,46 @@
+{
+  "name": "default",
+  "description": "Full workspace with all skills and templates",
+  "skills": [
+    "prd",
+    "eng-spec",
+    "requirements",
+    "todo",
+    "summary",
+    "meeting-notes",
+    "release-plan",
+    "seo-brief",
+    "landing-page-copy",
+    "adr",
+    "apidoc",
+    "changelog",
+    "commit",
+    "completetodo",
+    "createtodo",
+    "deadcode",
+    "debug",
+    "deps",
+    "e2e",
+    "envcheck",
+    "explain",
+    "migration",
+    "openpr",
+    "opentodos",
+    "perf",
+    "readme",
+    "rebase",
+    "release",
+    "standup",
+    "storecontext",
+    "test",
+    "testcoverage"
+  ],
+  "templates": [
+    "PRD_TEMPLATE.md",
+    "ENG_SPEC_TEMPLATE.md",
+    "DECISION_RECORD_TEMPLATE.md",
+    "WEEKLY_REVIEW_TEMPLATE.md",
+    "PROJECT_INDEX_TEMPLATE.md"
+  ],
+  "claudeMdTemplate": "default.md"
+}

package/assets/profiles/engineering-exec.json

@@ -0,0 +1,42 @@
+{
+  "name": "engineering-exec",
+  "description": "Engineering leadership — specs, planning, and requirements",
+  "skills": [
+    "prd",
+    "eng-spec",
+    "requirements",
+    "todo",
+    "release-plan",
+    "adr",
+    "apidoc",
+    "changelog",
+    "commit",
+    "completetodo",
+    "createtodo",
+    "deadcode",
+    "debug",
+    "deps",
+    "e2e",
+    "envcheck",
+    "explain",
+    "migration",
+    "openpr",
+    "opentodos",
+    "perf",
+    "readme",
+    "rebase",
+    "release",
+    "standup",
+    "storecontext",
+    "test",
+    "testcoverage"
+  ],
+  "templates": [
+    "PRD_TEMPLATE.md",
+    "ENG_SPEC_TEMPLATE.md",
+    "DECISION_RECORD_TEMPLATE.md",
+    "WEEKLY_REVIEW_TEMPLATE.md",
+    "PROJECT_INDEX_TEMPLATE.md"
+  ],
+  "claudeMdTemplate": "engineering-exec.md"
+}

package/assets/profiles/indie-maker.json

@@ -0,0 +1,32 @@
+{
+  "name": "indie-maker",
+  "description": "Solo builders — lean planning, shipping, and iteration",
+  "skills": [
+    "prd",
+    "todo",
+    "summary",
+    "release-plan",
+    "changelog",
+    "commit",
+    "completetodo",
+    "createtodo",
+    "debug",
+    "deps",
+    "e2e",
+    "envcheck",
+    "explain",
+    "openpr",
+    "opentodos",
+    "readme",
+    "release",
+    "standup",
+    "storecontext",
+    "test"
+  ],
+  "templates": [
+    "PRD_TEMPLATE.md",
+    "DECISION_RECORD_TEMPLATE.md",
+    "PROJECT_INDEX_TEMPLATE.md"
+  ],
+  "claudeMdTemplate": "indie-maker.md"
+}

package/assets/profiles/marketing.json

@@ -0,0 +1,27 @@
+{
+  "name": "marketing",
+  "description": "Content and marketing — copy, SEO, and communication",
+  "skills": [
+    "prd",
+    "summary",
+    "meeting-notes",
+    "seo-brief",
+    "landing-page-copy",
+    "commit",
+    "completetodo",
+    "createtodo",
+    "envcheck",
+    "explain",
+    "openpr",
+    "opentodos",
+    "readme",
+    "standup",
+    "storecontext"
+  ],
+  "templates": [
+    "PRD_TEMPLATE.md",
+    "WEEKLY_REVIEW_TEMPLATE.md",
+    "PROJECT_INDEX_TEMPLATE.md"
+  ],
+  "claudeMdTemplate": "marketing.md"
+}

package/assets/skills/adr/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: adr
+description: "Create Architecture Decision Records (ADRs). Use when the user says /adr, asks to document an architecture decision, record a technical decision, or wants to create an ADR. Triggers: adr, architecture decision, decision record, technical decision, design decision, why did we choose."
+---
+
+# ADR (Architecture Decision Record) Generator
+
+Create well-structured Architecture Decision Records.
+
+## Workflow
+
+1. **Determine ADR location and numbering:**
+   - Check for existing ADR directory: `docs/adr/`, `docs/decisions/`, `adr/`, `doc/architecture/decisions/`.
+   - If none exists, create `docs/adr/`.
+   - Find the next sequence number from existing ADR files.
+   - File naming: `NNNN-<kebab-case-title>.md` (e.g., `0005-use-postgresql-for-persistence.md`).
+
+2. **Gather the decision context:**
+   - What problem or question prompted this decision?
+   - What constraints exist (technical, business, team)?
+   - What options were considered?
+
+3. **Generate the ADR using this template:**
+
+```markdown
+# <NUMBER>. <Title>
+
+Date: YYYY-MM-DD
+
+## Status
+
+<Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md)>
+
+## Context
+
+<What is the issue that we're seeing that is motivating this decision or change?>
+
+## Decision
+
+<What is the change that we're proposing and/or doing?>
+
+## Consequences
+
+### Positive
+- <benefit>
+
+### Negative
+- <trade-off>
+
+### Neutral
+- <side effect>
+```
+
+4. **Link related ADRs:**
+   - If this supersedes a previous decision, update the old ADR's status.
+   - Cross-reference related decisions.
+
+## Guidelines
+
+- Use the format from [Michael Nygard's ADR template](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) as the default.
+- Keep the context section factual and objective.
+- List all options considered, not just the chosen one.
+- Be explicit about trade-offs in consequences.
+- Write for a future team member who needs to understand *why* this decision was made.
+- Status should be "Proposed" unless the user specifies it's already accepted.
+- If the user describes a decision conversationally, extract the structured ADR from their description.

package/assets/skills/apidoc/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: apidoc
+description: "Generate API documentation from code. Use when the user says /apidoc, asks to document an API, generate API docs, create endpoint documentation, or produce an OpenAPI/Swagger spec. Triggers: api doc, api documentation, endpoint docs, swagger, openapi, REST docs, API reference, document routes."
+---
+
+# API Documentation Generator
+
+Generate comprehensive API documentation from code.
+
+## Workflow
+
+1. **Identify the API framework:**
+   - Express, Fastify, Koa, Hono (Node.js)
+   - Flask, FastAPI, Django REST Framework (Python)
+   - Gin, Echo, Chi (Go)
+   - Actix, Axum (Rust)
+   - Spring Boot (Java)
+   - Or a raw OpenAPI/Swagger spec.
+
+2. **Discover endpoints:**
+   - Scan route definitions, controllers, and handler files.
+   - For each endpoint, extract: method, path, parameters, request body, response, middleware/guards.
+
+3. **For each endpoint, document:**
+
+```markdown
+### <METHOD> <path>
+
+<Brief description>
+
+**Authentication:** <Required/Optional/None>
+
+**Parameters:**
+| Name | In | Type | Required | Description |
+|------|-----|------|----------|-------------|
+| id   | path | string | yes | Resource ID |
+
+**Request Body:**
+```json
+{
+  "field": "type — description"
+}
+```
+
+**Responses:**
+| Status | Description |
+|--------|-------------|
+| 200    | Success — returns <shape> |
+| 400    | Validation error |
+| 401    | Unauthorized |
+| 404    | Not found |
+
+**Example:**
+```bash
+curl -X GET https://api.example.com/resource/123 \
+  -H "Authorization: Bearer <token>"
+```
+```
+
+4. **Choose output format based on user preference:**
+   - **Markdown** — readable docs for a README or docs site.
+   - **OpenAPI 3.x YAML/JSON** — machine-readable spec for Swagger UI, Redoc, Postman.
+   - **Both** — generate both formats.
+
+5. **If generating OpenAPI spec:**
+   - Include `info`, `servers`, `paths`, `components/schemas`.
+   - Derive schemas from TypeScript types, Pydantic models, or Go structs.
+   - Validate the spec with a linter if available.
+
+## Guidelines
+
+- Derive documentation from actual code, not guesses.
+- Include realistic example values in request/response samples.
+- Document error responses, not just happy paths.
+- Group endpoints by resource or domain (e.g., Users, Products, Orders).
+- Note rate limits, pagination, and versioning if present in the code.
+- If auth middleware exists, document the auth mechanism.
+- For GraphQL APIs, document queries, mutations, and subscriptions instead.