project-logbook 1.1.0 → 1.2.0

package/src/templates/CONTRIBUTING.md

@@ -65,7 +65,17 @@ Once the work is ready:
 
 The linter enforces rules to be followed.
 
-### 4. Final Review
+### 4. Interactive Local QA Loop
+Development is an iterative process. Expect to go through several feedback loops with the prompter before a ticket is finalized:
+- **Test & Challenge**: The prompter will run and test your changes, challenge architectural patterns, and suggest revisions.
+- **Cycle Routine**: During each feedback round:
+  1. Update code according to feedback.
+  2. Log key decisions, errors, and pivots in `log.md` (`logbook log "..."`).
+  3. Keep the story in `index.md` fully up-to-date with any design/code changes.
+  4. Run `npm run pre` to verify linting and tests pass.
+- **Commit Optimization**: Once the implementation is solid, optimize the final git commit message to match project standards before releasing.
+
+### 5. Final Review
 Use the preview command to see how your entry looks in the context of the whole project:
 ```bash
 logbook preview
@@ -88,9 +98,31 @@ If `jiraPrefix` is configured, entry folder names and ticket references must mat
 
 ## Research Logs
 For exploratory research, technical spike investigations, and architectural decision groundwork, we use **Research Logs**.
-- **Location**: Stored in `docs/research/` (configurable via `researchDir`).
-- **Scaffolding**: Run `logbook new [ID] [Slug] --research` or `logbook new -r` to scaffold. This automatically generates a numeric ID prefixed with `RES-` (e.g. `RES-1`).
+
+- **Required Setup**: Before creating your first research log, ensure that your configured research directory exists on your filesystem (for example, create it using `mkdir -p docs/research`).
+- **Location**: Stored in `docs/research/` (configurable via `researchDir` in `.project-logbook`).
+- **Scaffolding**: Run `logbook new [ID] [Slug] --research` or `logbook new -r` to scaffold. This automatically generates a numeric ID prefixed with `RES-` (e.g., `RES-1`).
 - **Commands**: Commands like `logbook start RES-1`, `logbook log`, and `logbook release` work transparently.
 - **Auto-Activity Tracking**: Writing a log message via `logbook log` automatically updates the `updated` frontmatter field inside the research log's `index.md`.
 - **Status Lifecycle**: The frontmatter `status` field tracks progress: `active`, `paused`, `postponed`, or `completed`.
 - **Visuals**: Research logs are compiled and displayed under a dedicated "Research" tab on the built logbook homepage, sorted by their latest `updated` date.
+
+## Custom Storyline Types
+Beyond standard logbook entries and Research Logs, you can define completely custom storyline types (e.g., "analyses", "spikes", "decisions") in `.project-logbook`.
+
+- **Required Setup**: Define the custom types inside your `.project-logbook` configuration file under `customTypes` and ensure the directory exists on your filesystem:
+  ```json
+  {
+    "customTypes": {
+      "analyses": {
+        "prefix": "ANA",
+        "dir": "docs/analyses",
+        "tabTitle": "Analyses",
+        "sortBy": "updated"
+      }
+    }
+  }
+  ```
+- **Directory Setup**: Ensure the directory configured (e.g., `docs/analyses`) is created on your filesystem (for example, create it using `mkdir -p docs/analyses`).
+- **Scaffolding**: Run `logbook new [ID] [Slug] --type analyses` or `logbook new -t analyses` to scaffold the entry.
+- **Visuals**: Just like Research Logs, these custom types will automatically compile into dedicated tabs on the built logbook homepage using your specified `tabTitle`.

package/src/templates/adr.md

@@ -0,0 +1,34 @@
+---
+id: [ID_NUM]
+title: [YAML_TITLE]
+status: "proposed"
+date: [DATE]
+author: "[AUTHOR]"
+superseded_by: null
+tags: []
+---
+
+# ADR [ID]: [TITLE]
+
+## Context
+[Describe the issue motivating this decision and any context that influences it.]
+
+## Considered Options
+1. **[Option A]**: [Brief description.]
+2. **[Option B]**: [Brief description.]
+
+## Decision
+[State the decision and briefly explain what it means in practice.]
+
+## Rationale
+[Explain why this option was chosen over the alternatives.]
+
+## Consequences
+
+### Positive
+*   [Benefit 1]
+*   [Benefit 2]
+
+### Negative
+*   [Drawback 1]
+*   [Drawback 2]

package/src/templates/index.md

@@ -2,7 +2,7 @@
 # The ticket field should match the ID portion (e.g., LB-34)
 ticket: {{id}}
 # The title should be a human-readable description of the work
-title: {{title}}
+title: {{yamlTitle}}
 prompter: "[PROMPTER]"
 harness: "[HARNESS]"
 llm: "[LLM]"
@@ -27,9 +27,10 @@ TODO: Write a polished, highly readable ticket summary that reads like an engagi
 
 ### Formatting & Style Rules:
 - **Maintain the narrative tone:** TODO: Keep the storytelling flair (e.g., describing how problems accumulated or how gaps surfaced), but stay strictly factual based on the provided changes.
-- **Add thematic headings:** TODO: Break the narrative down into logical chapters using Markdown headings (e.g., ### The Friction Points, ### The Fix, ### Closing the Gap).
-- **Use bullet points:** TODO: Whenever listing multiple items (like friction points, test scenarios, or rewritten paths), use a bulleted list instead of a dense paragraph to make it scannable.
+- **Add thematic headings:** TODO: Break the narrative down into logical chapters using action-oriented Markdown subheadings that describe what was improved/solved (e.g., ### Improving TabGroup Accessibility, ### Binding Dialog Colors to the Theme) rather than dry, generic headers like "Friction" or "The Fix".
+- **Avoid forced bullet points:** TODO: Write in natural, flowing paragraphs (like in a dev blog post). Only use bullet points for actual, simple lists of items (e.g., list of modified files or configuration options), never to structure or split your main story thoughts.
 - **Use bold emphasis:** TODO: Bold key concepts, problems, and solutions to guide the reader's eye.
 - **Format code:** TODO: Use inline backticks for files, plugins, HTML elements, and code snippets (e.g., `src/lib/build-helpers.ts`).
-- **Keep paragraphs short:** TODO: Ensure no paragraph is longer than 3-4 sentences. Keep the pacing quick and engaging.
+- **Keep paragraphs short:** TODO: Ensure no paragraph is longer than 4 sentences. Keep the pacing quick and engaging.
+- **Weave the narrative:** TODO: Do not list all friction points in one massive block followed by all fixes/solutions in another. Instead, weave them together chronologically or by component/theme (e.g., describe the friction and its corresponding fix within the same chapter or paragraph).
 - **Do not state the obvious**: TODO: Passed tests, lints, pre-commit suites are mandatory and no ticket is released without this. This does not need to be mentioned

package/src/templates/steer.txt

@@ -33,9 +33,22 @@ You MUST log your work continuously using `logbook log "<message>"`. This is not
 Phase 3: Synthesize
 1. When implementation is finished, write the narrative in `index.md`.
 2. Storytelling Mode: Explain the "Why" and the "Journey." Avoid simple technical bullet points.
+   - **Keep paragraphs short**: Max 4 sentences per paragraph to ensure fast-paced, readable prose.
+   - **Use bold & code formatting**: Use inline backticks for files/code, and bolding for key terms/problems.
+   - **Structure with H3 headings**: Use action-oriented subheadings describing the topic/component modified (e.g., ### Improving TabGroup Accessibility, ### Binding Dialog Colors to the Theme) instead of generic "Friction" or "Fix" headers.
+   - **Avoid forced lists**: Write in natural, flowing paragraphs. Only use bullet points for simple lists of items (e.g., files modified, options checked), never to split or structure your core narrative thoughts.
+   - **Weave friction & fix**: Do not separate all problems into one block and all solutions into another. Weave them together chronologically or group them by component/theme.
 3. Clean up all template placeholders and complete the frontmatter (author, summary, dates).
 
 Phase 4: Verify
 1. Run `npm run pre` (which includes `logbook lint` and other quality gates).
 2. Ensure there are no linter errors, unreplaced placeholders, or architectural violations before concluding your work. 
-3. Hand back to the prompter, who will review and run `logbook release`.
+3. Hand back to the prompter for local QA/review.
+
+Phase 5: Local QA & Iterative Refinement
+1. Expect feedback loops: The prompter will test your changes, challenge decisions, and request refinements.
+2. In each iteration loop:
+   - Log decisions and pivots in `log.md` in real-time (`logbook log "<message>"`).
+   - Update the story in `index.md` to reflect any design/code changes.
+   - Run verification again (`npm run pre`).
+3. Optimize the git commit message (conforming to project standards) before final release.