@orderful/droid 0.45.1 → 0.47.0

package/dist/tools/project/skills/project/references/templates.md

@@ -1,14 +1,13 @@
 # Project Templates
 
-Templates vary by `preset` setting.
-
-## Markdown Preset (default)
-
-### PROJECT.md
+## PROJECT.md
 
 ```markdown
 ---
+type: project
 status: active
+created: {today}
+updated: {today}
 ---
 
 # Project: {Name}
@@ -33,15 +32,16 @@ status: active
 
 {Architecture, key files, patterns}
 
+## Related
+
+- {Links to related notes}
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
-
-### 0.1.0 - {today}
-- Initial project setup
 ```
 
-### CHANGELOG.md
+## CHANGELOG.md
 
 ```markdown
 # Changelog
@@ -54,58 +54,6 @@ All notable changes to the {Name} project.
 
 ---
 
-## Obsidian Preset
-
-### PROJECT.md
-
-```markdown
----
-type: project
-status: active
-created: {today}
-updated: {today}
----
-
-# Project: {Name}
-
-{Brief description}
-
-| | |
-|---|---|
-| **Version** | 0.1.0 |
-| **Started** | {today} |
-| **Status** | Active |
-
-## Overview
-
-{**What** this project does, **why** it exists}
-
-## Goals
-
-- {Goal 1}
-
-## Technical Details
-
-{Architecture, key files, patterns}
-
-## Related
-
-- {Links to related notes}
-
-## Changelog
-
-See [[CHANGELOG|full history]].
-
-### 0.1.0 - {today}
-- Initial project setup
-```
-
-### CHANGELOG.md
-
-Same as markdown preset.
-
----
-
 ## Template Variables
 
 | Variable | Expands To |
@@ -115,19 +63,23 @@ Same as markdown preset.
 | `{name}` | Project name (lowercase) |
 | `{kebab-name}` | Folder name (kebab-case) |
 
-## Preset Differences Summary
+## Link Style
+
+Templates show standard markdown links. When `preset` is `obsidian`, substitute wikilinks:
 
-| Feature | Markdown | Obsidian |
-|---------|----------|----------|
-| Links | `[text](path)` | `[[path\|text]]` |
-| YAML properties | Minimal (`status`) | Rich (`type`, `created`, `updated`) |
-| Related section | Optional | Included |
+| Standard (markdown) | Wikilink (obsidian) |
+|---------------------|---------------------|
+| `[CHANGELOG.md](CHANGELOG.md)` | `[[CHANGELOG]]` |
+| `[DECISIONS.md](DECISIONS.md)` | `[[DECISIONS]]` |
+| `[WORKLOG.md](WORKLOG.md)` | `[[WORKLOG]]` |
+
+This is the only difference between presets — structure, frontmatter, and sections are identical.
 
 ---
 
 ## Seeded from Codex
 
-When creating with `--from codex:{name}`, use this template variant. Works with both markdown and obsidian presets.
+When creating with `--from codex:{name}`, use this template variant.
 
 ### Additional Variables
 
@@ -145,7 +97,10 @@ When creating with `--from codex:{name}`, use this template variant. Works with
 
 ```markdown
 ---
+type: project
 status: active
+created: {today}
+updated: {today}
 codex_source: projects/{codex-name}
 ---
 
@@ -190,9 +145,6 @@ Personal working memory for {Name}, seeded from shared codex context.
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
-
-### 0.1.0 - {today}
-- Project created from codex:{codex-name}
 ```
 
 ### CHANGELOG.md (Seeded)
@@ -218,3 +170,95 @@ When extracting content from codex files:
 
 If a section is missing, use placeholder text:
 - `{To be extracted from codex or filled manually}`
+
+---
+
+## Companion Doc Templates
+
+Companion docs are **never** created at project start. They emerge when a project grows enough to benefit from them. See `creating.md` for when each is created.
+
+### DECISIONS.md
+
+Create when 3+ decisions have accumulated in PROJECT.md.
+
+**Table format (default)** — scales well for projects with many decisions:
+
+```markdown
+---
+type: decisions
+project: {Name}
+created: {today}
+updated: {today}
+---
+
+# Decisions
+
+Key decisions for the {Name} project.
+
+| # | Decision | Date | Context |
+|---|----------|------|---------|
+| 1 | {Decision title} | {YYYY-MM-DD} | {Brief rationale or link to discussion} |
+```
+
+**Rich format (alternative)** — for fewer, more significant decisions:
+
+```markdown
+---
+type: decisions
+project: {Name}
+created: {today}
+updated: {today}
+---
+
+# Decisions
+
+Key decisions for the {Name} project.
+
+## 1. {Decision Title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** Accepted
+
+{2-3 sentences of context and rationale. Link to plan or research doc if one exists.}
+```
+
+Choose the format that fits the project. Table for many small decisions, rich for fewer important ones. Mixing is fine — start with table, expand significant entries to rich format if needed.
+
+### WORKLOG.md
+
+Create when PROJECT.md exceeds ~300 lines with completed work items that can be archived.
+
+```markdown
+---
+type: worklog
+project: {Name}
+created: {today}
+updated: {today}
+---
+
+# Worklog
+
+Completed work for the {Name} project. Newest first.
+
+## {Title of completed work}
+
+{YYYY-MM-DD} · PR #{number} · [plan link if exists]
+
+{1-3 sentence narrative of what was done and why it mattered.}
+
+---
+
+## {Older completed work}
+
+{YYYY-MM-DD}
+
+{Brief narrative.}
+```
+
+### Worklog Entry Guidelines
+
+- **Title:** Descriptive, in past tense ("Restructured PROJECT.md", "Added permission controls")
+- **Metadata line:** Date is required, PR and plan links are optional
+- **Narrative:** Brief — it's an index, not a retelling. Link out to plans, research, PRs for detail.
+- **Order:** Reverse chronological (newest first)
+- **Separator:** Use `---` between entries for readability

package/dist/tools/project/skills/project/references/updating.md

@@ -17,18 +17,25 @@
    - Important file paths or code locations
    - Bug fixes or gotchas encountered
 
-3. **If significant new information found:**
+3. **Size check** (read current PROJECT.md and count lines):
+   - **Under ~300 lines:** Proceed normally
+   - **300–400 lines:** Look for archival opportunities — mention them in your proposal
+   - **Over 400 lines:** Actively identify content to archive (see "Archival to WORKLOG.md" below)
+
+4. **If significant new information found:**
    - Propose specific sections/content to add or update
+   - Include archival proposals if the size check warrants it
    - Show what will be changed
    - Ask for confirmation before proceeding
 
-4. **If no obvious updates:**
+5. **If no obvious updates:**
    - Ask what the user would like to update
    - Suggest sections: metadata, implementation details, technical decisions, notes
 
-5. **After approval:**
+6. **After approval:**
    - Read current project file
    - Make approved updates, preserving existing structure
+   - Route decisions appropriately (see "Decisions Routing" below)
    - Determine version bump (see `versioning.md`)
    - Add changelog entry (see `changelog.md`)
    - Confirm what was updated
@@ -46,7 +53,74 @@ Good project updates include:
 | **Progress** | "Completed validation layer, starting on UI" |
 | **File locations** | "Key files: `src/services/template.service.ts`" |
 
-## Example
+## Decisions Routing
+
+Decisions are captured differently depending on whether the project has a DECISIONS.md companion doc:
+
+1. **DECISIONS.md exists** → Add new decisions there. Add a brief reference in PROJECT.md only when the decision directly affects active work.
+2. **DECISIONS.md does not exist AND 3+ decisions in PROJECT.md** → Offer to create DECISIONS.md (from template in `templates.md`) and migrate existing decisions. Keep a summary reference in PROJECT.md.
+3. **Fewer than 3 decisions** → Keep inline in PROJECT.md as usual.
+
+When migrating, preserve the original decision date and context. Remove the detailed decision content from PROJECT.md, leaving just a "See DECISIONS.md" reference in the relevant section.
+
+## Archival to WORKLOG.md
+
+When the size check identifies archival opportunities, propose moving completed work items to a WORKLOG.md companion doc.
+
+### What to archive
+
+- **Completed** Current Work items (fully shipped, no active follow-ups)
+- **Previous Work** or **Done** sections
+- Inline decision tables with 5+ entries (migrate to DECISIONS.md instead)
+- Historical context that's useful for reference but not needed in active context
+
+### What NOT to archive
+
+- Active or in-progress work items
+- Technical details still relevant to current work
+- Architectural patterns or constraints that guide ongoing development
+- The Overview, Goals, or metadata sections
+
+### Archival procedure
+
+1. **Identify candidates** — List completed items with their approximate line counts
+2. **Propose archival** — Show before/after line counts so the user sees the impact:
+   ```
+   PROJECT.md is currently 427 lines. Proposed archival:
+   - "Completed: Permission Controls" (~35 lines) → WORKLOG.md
+   - "Completed: Template Rendering" (~28 lines) → WORKLOG.md
+   - Inline decisions table (12 entries) → DECISIONS.md
+
+   After: ~340 lines (saved ~87 lines)
+   ```
+3. **Create companion doc** if needed — Use templates from `templates.md`
+4. **Convert to worklog entries** — Condense each item to title + metadata line + 1-3 sentence narrative (see template guidelines)
+5. **Remove from PROJECT.md** — Delete the detailed content, not the section headers
+6. **Verify** — Confirm the archived content is preserved in the companion doc
+
+### Example
+
+```
+User: /project update
+
+Claude: I'll update #project-transaction-templates with learnings from this session.
+
+PROJECT.md is 382 lines — I also found archival opportunities.
+
+Proposed changes:
+- Add "Batch Processing" to Current Work with the patterns we established
+- Note the decision to use streaming for large payloads
+
+Proposed archival (saves ~45 lines):
+- "Permission Controls" (completed 2026-01-15) → WORKLOG.md
+- "Template Validation" (completed 2026-02-01) → WORKLOG.md
+
+This is a minor version bump (0.16.0 → 0.17.0).
+
+Proceed with these updates?
+```
+
+## Example (standard update)
 
 ```
 User: /project update

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.45.1",
+  "version": "0.47.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

package/src/tools/pii/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "droid-pii",
+  "version": "0.1.0",
+  "description": "Detect and redact PII (personally identifiable information) in text files. Powered by Microsoft Presidio with a bundled Python venv — zero external dependencies after first run.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "pii"
+  ],
+  "skills": [
+    "./skills/pii/SKILL.md"
+  ],
+  "commands": [
+    "./commands/pii.md"
+  ],
+  "agents": [
+    "./agents/pii-scanner.md"
+  ]
+}

package/src/tools/pii/TOOL.yaml

@@ -0,0 +1,22 @@
+name: pii
+description: "Detect and redact PII (personally identifiable information) in text files. Powered by Microsoft Presidio with a bundled Python venv — zero external dependencies after first run."
+version: 0.1.0
+status: beta
+
+includes:
+  skills:
+    - name: pii
+      required: true
+  commands:
+    - name: pii
+      is_alias: false
+  agents:
+    - pii-scanner
+
+dependencies: []
+
+prerequisites:
+  - name: python3
+    description: "Python 3.8+ required to run the Presidio venv"
+    check: "python3 --version"
+    install_hint: "Install Python 3 from python.org or via: brew install python3"

package/src/tools/pii/agents/pii-scanner.md

@@ -0,0 +1,85 @@
+---
+name: pii-scanner
+description: "Isolated PII analysis agent. Runs presidio-analyze.ts in a contained context so raw entity values never appear in the parent conversation. Use PROACTIVELY when the pii skill delegates scan operations."
+tools:
+  - Bash
+color: orange
+---
+
+You are a PII scanning agent. Your sole job is to run `presidio-analyze.ts` on a file or text and return a structured summary — without leaking raw PII values into the conversation.
+
+## Inputs
+
+You will receive:
+
+1. `file_path` — absolute path to the file to scan (preferred), OR
+2. `text_content` — inline text to scan (for small strings only)
+3. `entities` (optional) — comma-separated list of entity types to filter (e.g. `EMAIL_ADDRESS,PHONE_NUMBER`)
+4. `venv_path` (optional) — override for the Presidio venv path (default: `~/.droid/runtimes/presidio/`)
+
+## Rules
+
+- **Never echo raw PII values** in your output — return entity types, counts, and line numbers only
+- Make exactly one Bash call to `presidio-analyze.ts`
+- Parse the JSON result and return only the structured summary
+- If the script returns `init_required: true`, stop and tell the parent skill to run `presidio-init.ts` first
+- If the file does not exist, return a clear error
+
+## Procedure
+
+1. Build the command:
+   ```bash
+   droid exec pii presidio-analyze --file <file_path> [--entities <types>]
+   ```
+   (Use `--text` only for inline strings under ~1000 characters)
+
+2. Parse the JSON output from the script
+
+3. From the `entities` array, compute:
+   - `total_entities`: total count
+   - `by_type`: entity type → count map
+   - `lines_affected`: sorted unique list of line numbers
+   - `sample_lines`: up to 5 line numbers with the entity types found on each line
+
+4. Return the structured summary (see Output Format below)
+
+## Output Format
+
+Return JSON:
+
+```json
+{
+  "file": "/path/to/file.md",
+  "total_entities": 3,
+  "by_type": {
+    "EMAIL_ADDRESS": 2,
+    "PHONE_NUMBER": 1
+  },
+  "lines_affected": [4, 8, 12],
+  "sample_lines": [
+    { "line": 4, "types": ["EMAIL_ADDRESS"] },
+    { "line": 8, "types": ["PHONE_NUMBER"] },
+    { "line": 12, "types": ["EMAIL_ADDRESS"] }
+  ]
+}
+```
+
+If no entities are found:
+```json
+{
+  "file": "/path/to/file.md",
+  "total_entities": 0,
+  "by_type": {},
+  "lines_affected": [],
+  "sample_lines": []
+}
+```
+
+If an error occurs:
+```json
+{
+  "file": "/path/to/file.md",
+  "error": "...",
+  "init_required": true
+}
+```

package/src/tools/pii/commands/pii.md

@@ -0,0 +1,33 @@
+---
+name: pii
+description: "Detect and redact PII (personally identifiable information) in files and directories. Powered by Microsoft Presidio."
+argument-hint: "[scan | redact] {file|dir} [--entities TYPES] [--output PATH] [--dry-run] [--mask]"
+---
+
+# /pii
+
+**User invoked:** `/pii $ARGUMENTS`
+
+**Your task:** Invoke the **pii skill** with these arguments.
+
+## Examples
+
+- `/pii scan transcript.md`
+- `/pii scan ./meeting-notes/`
+- `/pii redact transcript.md --output transcript-clean.md`
+- `/pii redact transcript.md --dry-run`
+- `/pii redact transcript.md --entities PHONE_NUMBER,EMAIL_ADDRESS`
+
+## Quick Reference
+
+```bash
+/pii scan {file}                              # Scan file for PII
+/pii scan {dir}                               # Scan directory recursively
+/pii redact {file}                            # Redact PII (writes {file}-redacted.{ext})
+/pii redact {file} --output {out}             # Redact to specific output path
+/pii redact {file} --dry-run                  # Preview redactions without writing
+/pii redact {file} --entities TYPES           # Redact only specific entity types
+/pii redact {file} --mask                     # Use *** instead of <ENTITY_TYPE>
+```
+
+See the **pii skill** for full behaviour, procedure, and supported entity types.

package/src/tools/pii/skills/pii/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: pii
+description: "Detect and redact PII in text files and directories. Use when scanning files for sensitive data before sharing, or redacting emails, phone numbers, credit cards, SSNs, and other PII. User prompts like '/pii scan transcript.md' or '/pii redact meeting-notes/ --dry-run'."
+argument-hint: "[scan | redact] {file|dir} [--entities TYPES] [--output PATH] [--dry-run] [--mask]"
+allowed-tools: [Read, Glob, Grep, Bash, Task]
+---
+
+# PII Skill
+
+Detect and redact personally identifiable information using Microsoft Presidio — deterministic pattern matching + NER, fully offline after first run.
+
+## Usage
+
+```bash
+/pii scan transcript.md                          # Scan a file for PII
+/pii scan ./meeting-notes/                       # Scan a directory recursively
+/pii redact transcript.md                        # Redact PII in-place (writes to transcript-redacted.md)
+/pii redact transcript.md --output clean.md      # Redact to specific output file
+/pii redact transcript.md --dry-run              # Preview redactions without writing
+/pii redact transcript.md --entities PHONE_NUMBER,EMAIL_ADDRESS  # Redact specific types only
+/pii redact transcript.md --mask                 # Use *** instead of <ENTITY_TYPE> placeholders
+```
+
+## Procedure
+
+### Step 0: Ensure Presidio venv is ready
+
+Before any scan or redact operation, verify the venv exists:
+
+```bash
+droid exec pii presidio-init
+```
+
+On first run this takes ~2–3 min (downloads Presidio packages + spaCy en_core_web_lg model). Subsequent runs return immediately (`already_existed: true`).
+
+If init fails, surface the error and stop — do not attempt to run analysis without the venv.
+
+### Step 1: Route on subcommand
+
+Parse the first argument:
+- `scan` → proceed to Step 2
+- `redact` → proceed to Step 3
+- anything else → show usage and stop
+
+### Step 2: Scan (delegate to pii-scanner agent)
+
+The `pii-scanner` agent runs analysis in an isolated context so raw PII values never appear in the parent conversation.
+
+**For a single file:**
+Delegate to the `pii-scanner` agent with `file_path` set to the absolute path.
+
+**For a directory:**
+Use `Glob` to find text files matching: `**/*.{md,txt,ts,js,json,yaml,yml,csv,html,xml}`
+Delegate each file to `pii-scanner` individually and aggregate results.
+
+**Display results:**
+Show entity types, counts, and affected line numbers only — never print raw PII values.
+
+Example output:
+```
+transcript.md: 3 PII entities found
+  EMAIL_ADDRESS × 2  (lines 4, 12)
+  PHONE_NUMBER × 1   (line 8)
+```
+
+### Step 3: Redact (run presidio-redact.ts directly)
+
+```bash
+droid exec pii presidio-redact \
+  --file <path> \
+  [--output <path>] \
+  [--dry-run] \
+  [--entities <TYPES>] \
+  [--mask]
+```
+
+Parse the JSON result and display:
+- Number of entities found and redacted
+- Output file path (if written)
+- In `--dry-run` mode: show a brief diff preview (first 10 redacted lines), but do NOT echo the full `redacted_text` field by default
+
+**Never echo `redacted_text` in full to the terminal** unless the user explicitly requests it.
+
+### Step 4: Format and present results
+
+- Always show: entity type, count, affected lines
+- On success for redact: confirm output path and entity counts
+- On failure: surface the error from the script's `error` field with actionable next steps
+
+## Behaviour Rules
+
+- **Never print raw PII values** to the terminal — always show types + line numbers only
+- For `--dry-run` redact, show a preview diff (10 lines max) not the full document
+- If `python3` is not found, show a clear install message from the prerequisite check
+- Binary files and unknown extensions are skipped during directory scans
+- The `pii-scanner` agent handles the isolation boundary for `scan`; `redact` operates directly since the redacted output is the goal
+- Supported entity types are listed in `references/supported-entities.md`