docs: add second-brain example workflows

README.md

@@ -7,8 +7,7 @@ This repository contains the Agentic package workspace.
 | Package | Path | Purpose |
 |---|---|---|
 | `@tnezdev/agentic` | `packages/agentic` | Core primitives and CLI |
-
-Runtime packages will live beside the core package under `packages/`.
+| `@tnezdev/agentic-runtime-local` | `packages/agentic-runtime-local` | Local runtime package |
 
 ## Development
 
@@ -21,3 +20,10 @@ bun run build
 ```
 
 The dogfood workspace still lives at `.agentic/`. Start with [`.agentic/ONRAMP.md`](.agentic/ONRAMP.md), then read [`packages/agentic/AGENTS.md`](packages/agentic/AGENTS.md) for core package architecture.
+
+## Examples
+
+- [`.agentic/`](.agentic/) is the project dogfood workspace — a persona, skills, workflow, tasks, and memories used to build Agentic itself. Read [`.agentic/ONRAMP.md`](.agentic/ONRAMP.md) for the maintainer flow.
+- [`examples/second-brain/`](examples/second-brain/) is a user-mode example. It shows how an agent harness can use Agentic primitives to run second-brain workflows with persona activation, task pickup, workflow gates, and finalized artifacts. Memory is intentionally left for user space and custom adapters.
+
+The second-brain example includes its own [`AGENTS.md`](examples/second-brain/AGENTS.md) bootstrap file for harnesses.

examples/second-brain/.agentic/artifacts/01KTC500000000000000000010/meta.json

@@ -0,0 +1,16 @@
+{
+  "id": "01KTC500000000000000000010",
+  "type": "research-brief",
+  "title": "Visible Switch Options Research Seed",
+  "body_ref": "01KTC500000000000000000010/v1.md",
+  "version": 1,
+  "finalized": true,
+  "tags": [
+    "second-brain",
+    "research",
+    "example",
+    "para:resource/agentic-examples"
+  ],
+  "created_at": "2026-06-05T16:00:00.000Z",
+  "updated_at": "2026-06-05T16:00:00.000Z"
+}

examples/second-brain/.agentic/artifacts/01KTC500000000000000000010/v1.md

@@ -0,0 +1,35 @@
+# Visible Switch Options Research Seed
+
+## Question
+
+What physical or software-visible switch options could support a private second-brain input workflow?
+
+## Why It Matters
+
+A second-brain system gets better when capture is low-friction and intentional. A visible switch can make mode changes explicit: capture, focus, do-not-disturb, or research intake.
+
+## Findings
+
+- The useful axis is not hardware versus software. It is whether the switch state is observable by the host runtime.
+- A good switch should expose state, not just fire an event. Agents need to know the current mode after restarts.
+- The example should not bake in a particular device. Agentic should model the research loop and durable output, while the host runtime owns device integration.
+
+## Tradeoffs
+
+- Hardware switches are tangible and reliable, but integration is host-specific.
+- Software toggles are portable and easier to demo, but less physically salient.
+- Calendar or focus-mode signals may already exist, but they can blur user intent with ambient context.
+
+## Recommendation
+
+For a public Agentic example, keep the switch question as seed content only. Demonstrate the reusable second-brain research loop, not a device-specific integration.
+
+## Sources Consulted
+
+- Example seed only. Replace with real source notes during a live research pass.
+
+## Follow-Up Questions
+
+- Which host runtime will observe switch state?
+- Does the user need momentary events, durable state, or both?
+- Should switch state become memory, dispatch context, or runtime-local state?

examples/second-brain/.agentic/config.toml

@@ -0,0 +1,12 @@
+# Agentic configuration for the second-brain example.
+
+adapter = "filesystem"
+
+[memory]
+dir = ".agentic/memory"
+default_tier = "L1"
+dream_depth = "3"
+
+[workflow]
+graphs_dir = ".agentic/workflows"
+runs_dir = ".agentic/runs"

examples/second-brain/.agentic/personas/researcher.md

@@ -0,0 +1,44 @@
+---
+name: researcher
+description: Activate when turning an open question into a concise second-brain research brief
+memory_tags: [second-brain, research]
+skills: [research-brief, project-kickoff]
+task_filter:
+  tags: [research]
+  status: ready
+workflow: research-loop
+effort: medium
+reasoning: high
+---
+
+# Second-Brain Researcher
+
+You are maintaining a second-brain research workspace from `{{cwd}}` on `{{hostname}}`.
+The current time is `{{timestamp}}`.
+
+## Operating Principles
+
+- Start by restating the question and the decision it supports.
+- Prefer durable findings over exhaustive notes.
+- Separate evidence, interpretation, and recommendation.
+- Preserve uncertainty. If a source is weak, say so.
+- Write the output as an artifact that can be read later without the transcript.
+
+## Before Research
+
+1. Check `task next` for the active research question.
+2. Run the `research-brief` skill for the work procedure.
+3. If user memory is configured, recall relevant context tagged `second-brain` and `research`.
+4. Use the `research-loop` workflow when the question spans more than one pass.
+
+## Output Shape
+
+Produce a brief with:
+
+- Question
+- Why it matters
+- Findings
+- Tradeoffs
+- Recommendation
+- Sources consulted
+- Follow-up questions

examples/second-brain/.agentic/skills/project-kickoff/skill.md

@@ -0,0 +1,76 @@
+---
+name: project-kickoff
+description: Activate when an agent needs to turn a project idea into a scoped PARA project without guessing the user's intent
+tags: [second-brain, project, para, intake]
+---
+
+# Project Kickoff
+
+Use this procedure when the user wants to start or shape a project in a second-brain workspace.
+
+## Principles
+
+- Organize by actionability. A project exists to support a concrete outcome, not to classify information by broad subject.
+- A project is a short-term effort with a goal. If it has no finish line, it is probably an area, resource, or habit instead.
+- Do not draft a project plan from a title alone. First gather enough intent to avoid creating plausible but wrong tasks.
+- Keep the first plan lightweight. The goal is clarity and movement, not a perfect system.
+- End with the next essential step, not an exhaustive backlog.
+
+## Intake First
+
+Before creating a `project-plan` artifact, ask concise questions. Prefer 3-5 questions at a time.
+
+Ask about:
+
+- Outcome: What should be true when this project is done?
+- Motivation: Why does this matter now?
+- Scope: What is in bounds, and what is explicitly out of bounds for the first pass?
+- Constraints: Are there deadlines, tools, people, budgets, or standards to respect?
+- Current state: What already exists, and where is the messy input coming from?
+- Success criteria: How will we know this worked?
+- First useful action: What would create momentum without overbuilding?
+
+If the user already gave enough context, summarize your assumptions and ask for confirmation before creating durable artifacts. If the user explicitly asks for a speculative draft, label assumptions clearly.
+
+## PARA Placement
+
+Choose a concrete project bucket tag:
+
+```text
+para:project/<slug>
+```
+
+If the work is ongoing with no completion point, suggest an area tag instead:
+
+```text
+para:area/<slug>
+```
+
+If it is reference material without an active outcome, suggest a resource tag:
+
+```text
+para:resource/<slug>
+```
+
+## Project Plan Artifact
+
+After intake, write a `project-plan` artifact with:
+
+- Outcome
+- Why It Matters
+- Success Criteria
+- Scope
+- Constraints
+- Current State
+- PARA Bucket
+- Milestones or Intermediate Packets
+- Risks
+- Current Next Actions
+
+Every project plan must include a `para:project/<slug>` tag unless the intake reveals it is not actually a project.
+
+## Next Actions
+
+Next actions should respect dependencies. Do not choose a later action if an earlier structure does not exist yet.
+
+For example, if the project is to create a reading queue, do not pick the first reading item until the queue surface, fields, and statuses exist. The better next action is to define the queue shape from the user's requirements.

examples/second-brain/.agentic/skills/research-brief/skill.md

@@ -0,0 +1,50 @@
+---
+name: research-brief
+description: Activate when an agent needs to convert a research question into a cited second-brain brief
+tags: [second-brain, research, artifact]
+---
+
+# Research Brief
+
+Use this procedure when the task is to answer a research question for later reuse.
+
+## Procedure
+
+1. Restate the question in one sentence.
+2. Identify the decision or action the answer should support.
+3. Gather a small set of high-signal sources. Prefer primary sources, official docs, source code, standards, and direct measurements.
+4. Extract findings as claims with source references. Do not preserve raw browsing notes unless they are necessary evidence.
+5. Synthesize tradeoffs. Call out uncertainty and missing information.
+6. Write a brief artifact. Keep it readable without the transcript.
+7. Validate that the artifact has at least one PARA bucket tag.
+8. Finalize the artifact once taxonomy validation passes.
+9. Add follow-up tasks only for unresolved questions that affect a decision.
+
+## Artifact Contract
+
+Write a `research-brief` artifact with these sections:
+
+- `Question`
+- `Why It Matters`
+- `Findings`
+- `Tradeoffs`
+- `Recommendation`
+- `Sources Consulted`
+- `Follow-Up Questions`
+
+Every artifact must include at least one PARA bucket tag in this form:
+
+```text
+para:<bucket>/<slug>
+```
+
+Allowed buckets are `project`, `area`, `resource`, and `archive`. Choose the bucket that describes where the brief belongs in the user's second-brain system.
+
+Do not finalize the artifact until this tag is present. Finalization means the brief is durable output for this research pass, not that it can never be superseded.
+
+## Quality Bar
+
+- A reader can tell what changed in their understanding.
+- Recommendation follows from the evidence.
+- Sources are named clearly enough to revisit.
+- Unknowns are explicit instead of hidden in confident prose.

examples/second-brain/.agentic/tasks/01KTC500000000000000000001.json

@@ -0,0 +1,18 @@
+{
+  "id": "01KTC500000000000000000001",
+  "description": "Research visible switch options for a private second-brain input workflow",
+  "status": "ready",
+  "tags": [
+    "second-brain",
+    "research",
+    "example"
+  ],
+  "annotations": [
+    {
+      "text": "Seed task for the public example. Replace with a real recurring research question in your own workspace.",
+      "timestamp": "2026-06-05T16:00:00.000Z"
+    }
+  ],
+  "created_at": "2026-06-05T16:00:00.000Z",
+  "updated_at": "2026-06-05T16:00:00.000Z"
+}

examples/second-brain/.agentic/workflows/monthly-review.json

@@ -0,0 +1,69 @@
+{
+  "id": "monthly-review",
+  "name": "Monthly review",
+  "description": "Review project portfolio, areas, resources, and goals at monthly cadence.",
+  "version": "1.0",
+  "nodes": [
+    {
+      "id": "summarize-month",
+      "label": "Summarize month",
+      "description": "Summarize major outputs, decisions, changes, and unresolved tensions from the month.",
+      "artifact": {
+        "type": "monthly-summary",
+        "description": "Narrative summary of the month.",
+        "required": true,
+        "tags": ["second-brain", "review", "monthly"]
+      }
+    },
+    {
+      "id": "review-portfolio",
+      "label": "Review portfolio",
+      "description": "Review active projects and areas for alignment, overcommitment, and stale commitments.",
+      "artifact": {
+        "type": "portfolio-review",
+        "description": "Monthly project and area portfolio review.",
+        "required": true,
+        "tags": ["second-brain", "project", "area"]
+      }
+    },
+    {
+      "id": "promote-resources",
+      "label": "Promote resources",
+      "description": "Identify reusable notes, briefs, and references that should become resource bucket material.",
+      "artifact": {
+        "type": "resource-review",
+        "description": "Resources to promote, merge, prune, or revisit.",
+        "required": true,
+        "tags": ["second-brain", "resource"]
+      }
+    },
+    {
+      "id": "choose-month-focus",
+      "label": "Choose month focus",
+      "description": "Choose the next month's priorities, constraints, and explicit not-now list.",
+      "artifact": {
+        "type": "monthly-plan",
+        "description": "Next month focus and planning decisions.",
+        "required": true,
+        "tags": ["second-brain", "review", "plan"]
+      }
+    },
+    {
+      "id": "finalize-review",
+      "label": "Finalize review",
+      "description": "Finalize the monthly review artifact and update tasks or memories with durable decisions.",
+      "artifact": {
+        "type": "finalized-artifact-ref",
+        "description": "Reference to finalized monthly review and updates made.",
+        "required": true,
+        "tags": ["second-brain", "artifact", "memory", "tasks"]
+      }
+    }
+  ],
+  "edges": [
+    { "from": "summarize-month", "to": "review-portfolio" },
+    { "from": "review-portfolio", "to": "promote-resources" },
+    { "from": "promote-resources", "to": "choose-month-focus" },
+    { "from": "choose-month-focus", "to": "finalize-review" }
+  ]
+}