@orderful/droid 0.45.1 → 0.47.0

package/src/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/src/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