docs: add second-brain example workflows

[tnez]

Summary

• add a user-mode second-brain example workspace with harness bootstrap docs
• add project kickoff, archive, review, inbox, and research workflows
• keep shipped example memory-free while documenting user-provided memory/adapters

Test plan

• bun src/cli/main.ts workflow list --base-dir examples/second-brain
• bun src/cli/main.ts skill run project-kickoff --base-dir examples/second-brain
• bun test
• bun run typecheck

[dottie-weaver]

Review: docs: add second-brain example workflows

Overall: This is strong, well-scoped work. The example is opinionated in the right ways — it draws a clear boundary between Agentic primitives and host-runtime responsibilities, and it uses that boundary to keep the example honest. A few observations:

What works well

• AGENTS.md as harness bootstrap — This is the right abstraction. It answers exactly the questions a generic harness has at startup without pretending Agentic is the harness.
• Memory is intentionally left out — Stating this explicitly and explaining why prevents the obvious "where are the memory examples?" question before it gets asked. The user-space memory adapter boundary is clear.
• PARA taxonomy enforced in workflow, not globally — The validate-taxonomy gate inside the research-loop workflow is the right call. Taxonomy rules are workspace-specific; encoding them in the workflow keeps Agentic primitive-neutral.
• Project-kickoff skill — The "intake first" principle (ask 3-5 concise questions before creating durable artifacts) is exactly right. This prevents the common agent failure mode of fabricating plausible project scopes from a title alone.

Things to consider

1. Research-brief skill: "Sources Consulted" field — The seed artifact has "Sources Consulted": "Example seed only. Replace with real source notes during a live research pass." This is fine as a seed, but the skill template might benefit from an explicit instruction like "If no external sources were consulted, state that explicitly rather than leaving the field empty" — otherwise agents tend to hallucinate citations to fill the section.

2. Yearly-review workflow: archive vs. direction ordering — The flow goes collect-year → identify-themes → archive-completed-work → set-direction. Consider whether archiving before setting direction could lose useful context. If a project is archived in step 3 that would have informed the direction decision in step 4, the yearly plan might miss a thread. Minor; up to you whether to flip or add a note.

3. Artifact ID format — The seed uses 01KTC500000000000000000010 which reads like a ULID-ish format but isn't explained. A one-liner in README or AGENTS.md about the expected ID format (or that Agentic generates these) would help users understand whether they need to provide their own IDs.

4. task_filter in researcher persona — The persona specifies task_filter: { tags: ["research"], status: "ready" } but the seeded task has "tags": ["second-brain", "research"]. This works because the filter matches on tags that include "research", but it's worth noting that the filter would not match if someone added only ["second-brain"] to a task. This is correct behavior, just making sure it's intentional.

5. README diff: "Working example" → "Examples" — The README now lists two examples (dogfood + second-brain). The link text for .agentic/ changed from "Read .agentic/ONRAMP.md for a tour" to "Read .agentic/ONRAMP.md for the maintainer flow". This is a subtle but important reframe — the dogfood workspace is now explicitly positioned as maintainer-facing, not user-facing. That's the right call given the second-brain example exists for users.

Summary

Ship-ready. The observations above are minor and most are "consider" rather than "change before merge." The core architecture — persona → skill → workflow → artifact with PARA taxonomy enforcement at the workflow level — is clean and genuinely useful as a reference implementation.

[dottie-weaver]

Review: docs: add second-brain example workflows

This is a strong, well-scoped PR. The second-brain example demonstrates every major Agentic primitive (persona, skills, workflows, tasks, artifacts) in a coherent, user-mode workspace that keeps public example memory-free by design. A few observations and suggestions:

What works well

• AGENTS.md as harness bootstrap is the right abstraction. It answers exactly the questions a generic harness needs at startup without becoming a second system prompt.
• Workflow-enforced taxonomy validation (write-brief → validate-taxonomy → finalize-brief) is a great pattern — second-brain rules are workspace-specific, so encoding them in the workflow rather than making them global Agentic behavior is the correct call.
• Memory intentionally left for user space. This avoids the trap of shipping fake/example memories that wouldn't match any real user's retention rules.
• Seed artifact demonstrates the expected output shape with a real-ish research question (visible switch options) rather than a "hello world" placeholder.
• README is excellent — explains what each primitive does, how they compose, the boundary between Agentic and the harness, and the dogfood loop. The "Why This Shape" section is the right kind of design rationale.
• project-kickoff skill correctly insists on intake questions before creating durable artifacts. This prevents the common agent failure mode of drafting plausible-but-wrong plans from a title alone.

Minor suggestions (non-blocking)

1. research-loop.json node validate-taxonomy — The description says "confirm it includes at least one valid PARA bucket tag." Consider adding what happens on failure: does the workflow loop back to write-brief, or does it halt? A single sentence would clarify the intended recovery path.

2. project-kickoff workflow intake-questions node has "type": "manual" — This is the only node with an explicit type. If this is intentional (to signal that this step requires human input), it might be worth a brief README note explaining the convention. If it's incidental, removing it keeps the workflow schema consistent.

3. AGENTS.md fallback path — The bun ../../src/cli/main.ts paths are useful for development but fragile if the example directory moves. A one-line note that these paths are relative to the repo root would prevent confusion.

4. Artifact ID format — The seed artifact uses 01KTC500000000000000000010 (ULID-ish). The zero-padded middle section suggests placeholder data. If Agentic generates real ULIDs in practice, this is fine. If someone might try to parse these, a README note that IDs are opaque would help.

5. yearly-review workflow — The collect-year node says "Gather monthly reviews, major artifacts..." This implies the workspace already has monthly reviews. In a fresh workspace this step would produce an empty collection. That's probably fine (identity-forming over time), but worth noting that the workflow assumes accumulated history.

Overall

Ship it. The example is coherent, the boundary between Agentic and the harness is clearly drawn, and the PARA taxonomy gate in workflows is a pattern worth showing. The suggestions above are polish, not blockers.

Approving.

[dottie-weaver]

Review: Second-Brain Example Workflows

Read the full diff. This is good — it lands a coherent public example that demonstrates the Agentic primitive set without becoming a host runtime. A few observations:

What works well

• Boundary discipline. The AGENTS.md boundary section is the strongest part. It names exactly what Agentic owns vs what the harness owns, and resists the temptation to leak host responsibilities in. This is the right line.
• Workflow-enforced taxonomy. The validate-taxonomy → finalize gate in research-loop is the correct pattern: workspace-specific rules encoded in workflow, not globally enforced by the framework. Keeps Agentic opinion-free about what a "valid" tag looks like.
• Seed artifact + task. Including a finalized research-brief as seed output gives newcomers a concrete target shape without reading docs. The seed task with its example annotation makes clear this is starter content, not real work.
• README as narrative. The README explains why each piece exists and how they compose, not just what files are present. The "What Is In Here" table is a fast on-ramp.

Things to consider before merging

1. Monthly/yearly review workflows feel heavy for a first example. The research-loop, project-kickoff, project-archive, and process-inbox workflows all demonstrate distinct Agentic patterns. The review workflows (weekly, monthly, yearly) are structurally similar — collect → review → choose → finalize — and a reader might wonder why three separate files instead of one parameterized review workflow. Consider: is the repetition making a point (each cadence is its own thing) or is it an artifact of writing them independently? If the former, a brief comment in README about why separate workflows exist would help. If the latter, one review workflow with a cadence parameter would be cleaner.

2. AGENTS.md fallback paths. The bun ../../src/cli/main.ts fallback is useful for development but will rot if the source tree restructures. Consider a bin script in the example or a Makefile target instead, or just note in README that the fallback is development-only and may break.

3. Config.toml dream_depth and default_tier. The config sets dream_depth = "3" and default_tier = "L1" but neither concept is explained in the README, AGENTS.md, or any other file in this PR. A reader copying this example will not know what these do or whether to change them. Either add a brief comment in config.toml or mention in README what they control.

4. project-kickoff workflow has a manual type node. This is the only node with an explicit type field. The other workflows leave type unspecified (presumably defaulting to something). Is manual a real Agentic primitive, or a convention this example is introducing? If the former, worth noting in README. If the latter, a comment on the node would clarify intent.

5. Artifact ID format. The seed artifact uses 01KTC500000000000000000010 which looks like an ULID variant. The task uses 01KTC500000000000000000001. No issue with the format itself, but the jump from 1 to 10 is a bit jarring when reading the example cold. A one-line comment in the task or artifact file noting these are example-only would prevent confusion.

Verdict

The core structure is solid and the boundary discipline is exactly right. Items 1-5 are polish, not blockers. Happy to see this merged after addressing the config.toml comment and the manual type clarity — the rest is optional.

Nice work on this. The "research operating system" framing in README is the right pitch for what Agentic is.

[tnez]

Leaving this as draft intentionally while we backfill the runtime-package path from #103. Once the local runtime is in place, this second-brain example should become the dogfood target for proving the runnable workflow story rather than merging as a static example first.

Next implementation pickup is #106: add the narrow agentic runtime CLI namespace.

[tnez]

Superseded by main at 3b90574. The local stack was rebuilt with the sanitized second-brain example, runtime invocation records, Pi harness support, templates, and the agentic run entrypoint, so this draft branch is stale.