Issue & Task Pipeline

I used Linear for a year ($20/month). It was great, but Claude Code couldn't read or write to it without a custom integration. GitHub Issues is free but has the same problem — it's a separate system that Claude has to API into.

Then I realized: if issues are just markdown files with YAML frontmatter, Claude can create, read, update, and close them with the tools it already has. Obsidian's Bases feature turns that frontmatter into queryable database views — filtered, sorted, and grouped like any issue tracker. No API, no subscription, no vendor lock-in.

Every code change starts with an issue. The issue flows through a status pipeline, optionally through a spec workflow for non-trivial features, and ends with a close sweep.

Status Flow

Issues can also move to canceled or superseded if they're no longer relevant.

Each issue is a markdown file with YAML frontmatter. The frontmatter is what Obsidian Bases queries against — every field matters.

---
id: "STAK-498"
title: "Fix JM Bullion price scraper reading wrong column"
type: bug
scope: user-facing
status: done
priority: 1
assignee: lbruton
created: "2026-03-20"
updated: "2026-03-22"
completed: "2026-03-22"
due: ""
parent:
tags:
  - issue
  - staktrakr
  - bug
---

## Description

JM Bullion eCheck prices are inflated by ~$200. The price extractor
is reading the Card/PayPal column instead of the eCheck/Wire column.

## Acceptance Criteria

- [ ] eCheck prices match the website's eCheck/Wire column
- [ ] Other vendors unaffected by the fix
- [ ] Poller redeployed to both Portainer and Fly.io

## Related Documentation

- [[StakTrakr Overview]] — poller pipeline context
- [[Remote Poller]] — Fly.io deployment
- [[Portainer]] — home deployment target

Field Reference

Each project has a counter file that auto-increments issue numbers. The /issue skill reads the counter, creates the file, and bumps the counter — all in one step.

---
prefix: STAK
next: 532
project: StakTrakr
tags:
  - system
  - counter
---

Project Prefixes

Sub-Issues

For work that breaks into sub-tasks under a parent issue, use letter suffixes: STAK-498-A, STAK-498-B. Sub-issues include a parent: "[[STAK-498]]" field in their frontmatter and don't increment the counter.

Obsidian Bases turns your frontmatter into a queryable database. Create .base files that filter, sort, and group your issues — just like Linear or Jira boards, but powered by local markdown.

Cross-Project View

A single Issues.base at the vault root shows all open issues across every project, sorted by priority and grouped by status. Each project folder also has its own Issues.base for a focused view.

What Bases Extracts

Bases reads your frontmatter fields and renders them as sortable, filterable columns:

• Issue ID — clickable link to the issue file
• Title — from frontmatter, not the filename
• Type — color-coded badge (bug = red, feature = blue)
• Priority — numeric sort (1 at top)
• Status — grouped by pipeline stage
• Days Open — computed from created date

Five skills manage the full issue lifecycle. Each is a SKILL.md file that Claude reads and follows.

/issue Skill Workflow

1. Read .claude/project.json for issuePrefix and issueTag
2. Read _counter.md → get next number (e.g., 532)
3. Write STAK-532.md with full frontmatter + description
4. Identify and link related vault pages in ## Related Documentation
5. Increment counter: next → 533
6. Read file back and VALIDATE all frontmatter fields
   (this is a hard gate — missing fields break Bases)
7. Confirm: "Created STAK-532: [title] at [path]"

GitHub Issues Policy

GitHub Issues are treated as an inbound-only public bug inbox. All internal planning, features, and specs stay in the vault. When a user reports a bug on GitHub:

1. Create a vault issue with scope: user-facing and type: bug
2. Reference the GH issue number in the body (not frontmatter)
3. Close the GH issue when the vault issue reaches done

Non-trivial features go through a four-phase spec workflow. Each phase produces a document, requires a dashboard approval, and feeds into the next phase.

The Four Phases

# Spec files live in the project's .spec-workflow directory
.spec-workflow/specs/STAK-498-price-scraper-fix/
  ├── requirements.md      # User stories, acceptance criteria
  ├── design.md            # Architecture, API designs, components
  ├── tasks.md             # Atomic tasks with _Prompt guidance
  └── Implementation Logs/
      ├── Task-1-log.md    # What was built, files changed
      └── Task-2-log.md

Task Format

Each task in tasks.md includes structured guidance that Claude uses during implementation:

## Task 1.1: Fix Price Column Selection
- [ ] Update column-aware parser to check eCheck first
- [ ] Add regression test for JM Bullion parsing

_Prompt: Role: Backend | Task: Fix price-extract.js column
  selection order | Restrictions: Don't change other vendors |
  Success: eCheck prices within $5 of website values

_Leverage: devops/pollers/shared/price-extract.js (existing parser)

_Requirements: Requirement #1, Acceptance Criteria #1

Implementation Logging

Before marking any task [x] (complete), the log-implementation tool must be called. This creates a searchable knowledge base of what was built, preventing duplicate API endpoints and components across future specs.

Three skills produce reports from your issue data — weekly progress summaries, project roadmaps, and automated close sweeps.

1. Create the issue directory

# In your Obsidian vault
mkdir -p Projects/MyProject/Issues

2. Create the counter

cat > Projects/MyProject/Issues/_counter.md << 'EOF'
---
prefix: PROJ
next: 1
project: MyProject
tags:
  - system
  - counter
---
EOF

3. Create an Obsidian Base view

# Create a .base file that queries your issues
cat > Projects/MyProject/Issues/Issues.base << 'EOF'
{
  "name": "MyProject Issues",
  "source": "folder:Projects/MyProject/Issues",
  "filter": { "property": "tags", "operator": "contains", "value": "issue" },
  "columns": ["id", "title", "type", "status", "priority", "created"],
  "sort": [{ "property": "priority", "direction": "asc" }]
}
EOF

4. Tell Claude about your project

Add issue routing to your project's .claude/project.json:

{
  "issuePrefix": "PROJ",
  "issueTag": "myproject",
  "issuePath": "Projects/MyProject/Issues"
}

5. Create your first issue

# In Claude Code
> /issue "Add user authentication" --type feature --priority 2