@cregis-dev/cckit 0.2.0 → 0.4.0

package/templates/ecc/commands/claw.md

@@ -0,0 +1,79 @@
+---
+description: Start the NanoClaw agent REPL — a persistent, session-aware AI assistant powered by the claude CLI.
+---
+
+# Claw Command
+
+Start an interactive AI agent session that persists conversation history to disk and optionally loads ECC skill context.
+
+## Usage
+
+```bash
+node scripts/claw.js
+```
+
+Or via npm:
+
+```bash
+npm run claw
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAW_SESSION` | `default` | Session name (alphanumeric + hyphens) |
+| `CLAW_SKILLS` | *(empty)* | Comma-separated skill names to load as system context |
+
+## REPL Commands
+
+Inside the REPL, type these commands directly at the prompt:
+
+```
+/clear      Clear current session history
+/history    Print full conversation history
+/sessions   List all saved sessions
+/help       Show available commands
+exit        Quit the REPL
+```
+
+## How It Works
+
+1. Reads `CLAW_SESSION` env var to select a named session (default: `default`)
+2. Loads conversation history from `~/.claude/claw/{session}.md`
+3. Optionally loads ECC skill context from `CLAW_SKILLS` env var
+4. Enters a blocking prompt loop — each user message is sent to `claude -p` with full history
+5. Responses are appended to the session file for persistence across restarts
+
+## Session Storage
+
+Sessions are stored as Markdown files in `~/.claude/claw/`:
+
+```
+~/.claude/claw/default.md
+~/.claude/claw/my-project.md
+```
+
+Each turn is formatted as:
+
+```markdown
+### [2025-01-15T10:30:00.000Z] User
+What does this function do?
+---
+### [2025-01-15T10:30:05.000Z] Assistant
+This function calculates...
+---
+```
+
+## Examples
+
+```bash
+# Start default session
+node scripts/claw.js
+
+# Named session
+CLAW_SESSION=my-project node scripts/claw.js
+
+# With skill context
+CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
+```

package/templates/ecc/rules/README.md

@@ -1,5 +1,4 @@
 # Rules
-
 ## Structure
 
 Rules are organized into a **common** layer plus **language-specific** directories:
@@ -17,7 +16,8 @@ rules/
 │   └── security.md
 ├── typescript/      # TypeScript/JavaScript specific
 ├── python/          # Python specific
-└── golang/          # Go specific
+├── golang/          # Go specific
+└── swift/           # Swift specific
 ```
 
 - **common/** contains universal principles — no language-specific code examples.
@@ -32,6 +32,7 @@ rules/
 ./install.sh typescript
 ./install.sh python
 ./install.sh golang
+./install.sh swift
 
 # Install multiple languages at once
 ./install.sh typescript python
@@ -53,6 +54,7 @@ cp -r rules/common ~/.claude/rules/common
 cp -r rules/typescript ~/.claude/rules/typescript
 cp -r rules/python ~/.claude/rules/python
 cp -r rules/golang ~/.claude/rules/golang
+cp -r rules/swift ~/.claude/rules/swift
 
 # Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
 ```
@@ -80,3 +82,22 @@ To add support for a new language (e.g., `rust/`):
    > This file extends [common/xxx.md](../common/xxx.md) with <Language> specific content.
    ```
 4. Reference existing skills if available, or create new ones under `skills/`.
+
+## Rule Priority
+
+When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence).
+
+- `rules/common/` defines universal defaults applicable to all projects.
+- `rules/golang/`, `rules/python/`, `rules/typescript/`, etc. override those defaults where language idioms differ.
+
+### Example
+
+`common/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this:
+
+> Idiomatic Go uses pointer receivers for struct mutation — see [common/coding-style.md](../common/coding-style.md) for the general principle, but Go-idiomatic mutation is preferred here.
+
+### Common rules with override notes
+
+Rules in `rules/common/` that may be overridden by language-specific files are marked with:
+
+> **Language note**: This rule may be overridden by language-specific rules for languages where this pattern is not idiomatic.

package/templates/ecc/rules/common/development-workflow.md

@@ -0,0 +1,37 @@
+# Development Workflow
+
+> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
+
+The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
+
+## Feature Implementation Workflow
+
+0. **Research & Reuse** _(mandatory before any new implementation)_
+   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
+   - **Exa MCP for research:** Use `exa-web-search` MCP during the planning phase for broader research, data ingestion, and discovering prior art.
+   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
+   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
+   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
+
+1. **Plan First**
+   - Use **planner** agent to create implementation plan
+   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
+   - Identify dependencies and risks
+   - Break down into phases
+
+2. **TDD Approach**
+   - Use **tdd-guide** agent
+   - Write tests first (RED)
+   - Implement to pass tests (GREEN)
+   - Refactor (IMPROVE)
+   - Verify 80%+ coverage
+
+3. **Code Review**
+   - Use **code-reviewer** agent immediately after writing code
+   - Address CRITICAL and HIGH issues
+   - Fix MEDIUM issues when possible
+
+4. **Commit & Push**
+   - Detailed commit messages
+   - Follow conventional commits format
+   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process

package/templates/ecc/rules/common/git-workflow.md

@@ -1,7 +1,6 @@
 # Git Workflow
 
 ## Commit Message Format
-
 ```
 <type>: <description>
 
@@ -21,25 +20,5 @@ When creating PRs:
 4. Include test plan with TODOs
 5. Push with `-u` flag if new branch
 
-## Feature Implementation Workflow
-
-1. **Plan First**
-   - Use **planner** agent to create implementation plan
-   - Identify dependencies and risks
-   - Break down into phases
-
-2. **TDD Approach**
-   - Use **tdd-guide** agent
-   - Write tests first (RED)
-   - Implement to pass tests (GREEN)
-   - Refactor (IMPROVE)
-   - Verify 80%+ coverage
-
-3. **Code Review**
-   - Use **code-reviewer** agent immediately after writing code
-   - Address CRITICAL and HIGH issues
-   - Fix MEDIUM issues when possible
-
-4. **Commit & Push**
-   - Detailed commit messages
-   - Follow conventional commits format
+> For the full development process (planning, TDD, code review) before git operations,
+> see [development-workflow.md](./development-workflow.md).

package/templates/ecc/rules/swift/coding-style.md

@@ -0,0 +1,47 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Swift specific content.
+
+## Formatting
+
+- **SwiftFormat** for auto-formatting, **SwiftLint** for style enforcement
+- `swift-format` is bundled with Xcode 16+ as an alternative
+
+## Immutability
+
+- Prefer `let` over `var` — define everything as `let` and only change to `var` if the compiler requires it
+- Use `struct` with value semantics by default; use `class` only when identity or reference semantics are needed
+
+## Naming
+
+Follow [Apple API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/):
+
+- Clarity at the point of use — omit needless words
+- Name methods and properties for their roles, not their types
+- Use `static let` for constants over global constants
+
+## Error Handling
+
+Use typed throws (Swift 6+) and pattern matching:
+
+```swift
+func load(id: String) throws(LoadError) -> Item {
+    guard let data = try? read(from: path) else {
+        throw .fileNotFound(id)
+    }
+    return try decode(data)
+}
+```
+
+## Concurrency
+
+Enable Swift 6 strict concurrency checking. Prefer:
+
+- `Sendable` value types for data crossing isolation boundaries
+- Actors for shared mutable state
+- Structured concurrency (`async let`, `TaskGroup`) over unstructured `Task {}`

package/templates/ecc/rules/swift/hooks.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Swift specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **SwiftFormat**: Auto-format `.swift` files after edit
+- **SwiftLint**: Run lint checks after editing `.swift` files
+- **swift build**: Type-check modified packages after edit
+
+## Warning
+
+Flag `print()` statements — use `os.Logger` or structured logging instead for production code.

package/templates/ecc/rules/swift/patterns.md

@@ -0,0 +1,66 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Swift specific content.
+
+## Protocol-Oriented Design
+
+Define small, focused protocols. Use protocol extensions for shared defaults:
+
+```swift
+protocol Repository: Sendable {
+    associatedtype Item: Identifiable & Sendable
+    func find(by id: Item.ID) async throws -> Item?
+    func save(_ item: Item) async throws
+}
+```
+
+## Value Types
+
+- Use structs for data transfer objects and models
+- Use enums with associated values to model distinct states:
+
+```swift
+enum LoadState<T: Sendable>: Sendable {
+    case idle
+    case loading
+    case loaded(T)
+    case failed(Error)
+}
+```
+
+## Actor Pattern
+
+Use actors for shared mutable state instead of locks or dispatch queues:
+
+```swift
+actor Cache<Key: Hashable & Sendable, Value: Sendable> {
+    private var storage: [Key: Value] = [:]
+
+    func get(_ key: Key) -> Value? { storage[key] }
+    func set(_ key: Key, value: Value) { storage[key] = value }
+}
+```
+
+## Dependency Injection
+
+Inject protocols with default parameters — production uses defaults, tests inject mocks:
+
+```swift
+struct UserService {
+    private let repository: any UserRepository
+
+    init(repository: any UserRepository = DefaultUserRepository()) {
+        self.repository = repository
+    }
+}
+```
+
+## References
+
+See skill: `swift-actor-persistence` for actor-based persistence patterns.
+See skill: `swift-protocol-di-testing` for protocol-based DI and testing.

package/templates/ecc/rules/swift/security.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Security
+
+> This file extends [common/security.md](../common/security.md) with Swift specific content.
+
+## Secret Management
+
+- Use **Keychain Services** for sensitive data (tokens, passwords, keys) — never `UserDefaults`
+- Use environment variables or `.xcconfig` files for build-time secrets
+- Never hardcode secrets in source — decompilation tools extract them trivially
+
+```swift
+let apiKey = ProcessInfo.processInfo.environment["API_KEY"]
+guard let apiKey, !apiKey.isEmpty else {
+    fatalError("API_KEY not configured")
+}
+```
+
+## Transport Security
+
+- App Transport Security (ATS) is enforced by default — do not disable it
+- Use certificate pinning for critical endpoints
+- Validate all server certificates
+
+## Input Validation
+
+- Sanitize all user input before display to prevent injection
+- Use `URL(string:)` with validation rather than force-unwrapping
+- Validate data from external sources (APIs, deep links, pasteboard) before processing

package/templates/ecc/rules/swift/testing.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+# Swift Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Swift specific content.
+
+## Framework
+
+Use **Swift Testing** (`import Testing`) for new tests. Use `@Test` and `#expect`:
+
+```swift
+@Test("User creation validates email")
+func userCreationValidatesEmail() throws {
+    #expect(throws: ValidationError.invalidEmail) {
+        try User(email: "not-an-email")
+    }
+}
+```
+
+## Test Isolation
+
+Each test gets a fresh instance — set up in `init`, tear down in `deinit`. No shared mutable state between tests.
+
+## Parameterized Tests
+
+```swift
+@Test("Validates formats", arguments: ["json", "xml", "csv"])
+func validatesFormat(format: String) throws {
+    let parser = try Parser(format: format)
+    #expect(parser.isValid)
+}
+```
+
+## Coverage
+
+```bash
+swift test --enable-code-coverage
+```
+
+## Reference
+
+See skill: `swift-protocol-di-testing` for protocol-based dependency injection and mock patterns with Swift Testing.

package/templates/ecc/skills/api-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: api-design
 description: REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
+origin: ECC
 ---
 
 # API Design Patterns

package/templates/ecc/skills/article-writing/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: article-writing
+description: Write articles, guides, blog posts, tutorials, newsletter issues, and other long-form content in a distinctive voice derived from supplied examples or brand guidance. Use when the user wants polished written content longer than a paragraph, especially when voice consistency, structure, and credibility matter.
+origin: ECC
+---
+
+# Article Writing
+
+Write long-form content that sounds like a real person or brand, not generic AI output.
+
+## When to Activate
+
+- drafting blog posts, essays, launch posts, guides, tutorials, or newsletter issues
+- turning notes, transcripts, or research into polished articles
+- matching an existing founder, operator, or brand voice from examples
+- tightening structure, pacing, and evidence in already-written long-form copy
+
+## Core Rules
+
+1. Lead with the concrete thing: example, output, anecdote, number, screenshot description, or code block.
+2. Explain after the example, not before.
+3. Prefer short, direct sentences over padded ones.
+4. Use specific numbers when available and sourced.
+5. Never invent biographical facts, company metrics, or customer evidence.
+
+## Voice Capture Workflow
+
+If the user wants a specific voice, collect one or more of:
+- published articles
+- newsletters
+- X / LinkedIn posts
+- docs or memos
+- a short style guide
+
+Then extract:
+- sentence length and rhythm
+- whether the voice is formal, conversational, or sharp
+- favored rhetorical devices such as parentheses, lists, fragments, or questions
+- tolerance for humor, opinion, and contrarian framing
+- formatting habits such as headers, bullets, code blocks, and pull quotes
+
+If no voice references are given, default to a direct, operator-style voice: concrete, practical, and low on hype.
+
+## Banned Patterns
+
+Delete and rewrite any of these:
+- generic openings like "In today's rapidly evolving landscape"
+- filler transitions such as "Moreover" and "Furthermore"
+- hype phrases like "game-changer", "cutting-edge", or "revolutionary"
+- vague claims without evidence
+- biography or credibility claims not backed by provided context
+
+## Writing Process
+
+1. Clarify the audience and purpose.
+2. Build a skeletal outline with one purpose per section.
+3. Start each section with evidence, example, or scene.
+4. Expand only where the next sentence earns its place.
+5. Remove anything that sounds templated or self-congratulatory.
+
+## Structure Guidance
+
+### Technical Guides
+- open with what the reader gets
+- use code or terminal examples in every major section
+- end with concrete takeaways, not a soft summary
+
+### Essays / Opinion Pieces
+- start with tension, contradiction, or a sharp observation
+- keep one argument thread per section
+- use examples that earn the opinion
+
+### Newsletters
+- keep the first screen strong
+- mix insight with updates, not diary filler
+- use clear section labels and easy skim structure
+
+## Quality Gate
+
+Before delivering:
+- verify factual claims against provided sources
+- remove filler and corporate language
+- confirm the voice matches the supplied examples
+- ensure every section adds new information
+- check formatting for the intended platform

package/templates/ecc/skills/backend-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: backend-patterns
 description: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.
+origin: ECC
 ---
 
 # Backend Development Patterns

package/templates/ecc/skills/clickhouse-io/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clickhouse-io
 description: ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads.
+origin: ECC
 ---
 
 # ClickHouse Analytics Patterns

package/templates/ecc/skills/coding-standards/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: coding-standards
 description: Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.
+origin: ECC
 ---
 
 # Coding Standards & Best Practices

package/templates/ecc/skills/configure-ecc/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: configure-ecc
 description: Interactive installer for Everything Claude Code — guides users through selecting and installing skills and rules to user-level or project-level directories, verifies paths, and optionally optimizes installed files.
+origin: ECC
 ---
 
 # Configure Everything Claude Code (ECC)
@@ -63,7 +64,23 @@ mkdir -p $TARGET/skills $TARGET/rules
 
 ## Step 2: Select & Install Skills
 
-### 2a: Choose Skill Categories
+### 2a: Choose Scope (Core vs Niche)
+
+Default to **Core (recommended for new users)** — copy `.agents/skills/*` plus `skills/search-first/` for research-first workflows. This bundle covers engineering, evals, verification, security, strategic compaction, frontend design, and Anthropic cross-functional skills (article-writing, content-engine, market-research, frontend-slides).
+
+Use `AskUserQuestion` (single select):
+```
+Question: "Install core skills only, or include niche/framework packs?"
+Options:
+  - "Core only (recommended)" — "tdd, e2e, evals, verification, research-first, security, frontend patterns, compacting, cross-functional Anthropic skills"
+  - "Core + selected niche" — "Add framework/domain-specific skills after core"
+  - "Niche only" — "Skip core, install specific framework/domain skills"
+Default: Core only
+```
+
+If the user chooses niche or core + niche, continue to category selection below and only include those niche skills they pick.
+
+### 2b: Choose Skill Categories
 
 There are 27 skills organized into 4 categories. Use `AskUserQuestion` with `multiSelect: true`:
 
@@ -76,11 +93,11 @@ Options:
   - "All skills" — "Install every available skill"
 ```
 
-### 2b: Confirm Individual Skills
+### 2c: Confirm Individual Skills
 
 For each selected category, print the full list of skills below and ask the user to confirm or deselect specific ones. If the list exceeds 4 items, print the list as text and use `AskUserQuestion` with an "Install all listed" option plus "Other" for the user to paste specific names.
 
-**Category: Framework & Language (16 skills)**
+**Category: Framework & Language (17 skills)**
 
 | Skill | Description |
 |-------|-------------|
@@ -91,6 +108,7 @@ For each selected category, print the full list of skills below and ask the user
 | `django-tdd` | Django testing with pytest-django, factory_boy, mocking, coverage |
 | `django-verification` | Django verification loop: migrations, linting, tests, security scans |
 | `frontend-patterns` | React, Next.js, state management, performance, UI patterns |
+| `frontend-slides` | Zero-dependency HTML presentations, style previews, and PPTX-to-web conversion |
 | `golang-patterns` | Idiomatic Go patterns, conventions for robust Go applications |
 | `golang-testing` | Go testing: table-driven tests, subtests, benchmarks, fuzzing |
 | `java-coding-standards` | Java coding standards for Spring Boot: naming, immutability, Optional, streams |
@@ -122,13 +140,23 @@ For each selected category, print the full list of skills below and ask the user
 | `tdd-workflow` | Enforces TDD with 80%+ coverage: unit, integration, E2E |
 | `verification-loop` | Verification and quality loop patterns |
 
+**Category: Business & Content (5 skills)**
+
+| Skill | Description |
+|-------|-------------|
+| `article-writing` | Long-form writing in a supplied voice using notes, examples, or source docs |
+| `content-engine` | Multi-platform social content, scripts, and repurposing workflows |
+| `market-research` | Source-attributed market, competitor, fund, and technology research |
+| `investor-materials` | Pitch decks, one-pagers, investor memos, and financial models |
+| `investor-outreach` | Personalized investor cold emails, warm intros, and follow-ups |
+
 **Standalone**
 
 | Skill | Description |
 |-------|-------------|
 | `project-guidelines-example` | Template for creating project-specific skills |
 
-### 2c: Execute Installation
+### 2d: Execute Installation
 
 For each selected skill, copy the entire skill directory:
 ```bash