DEV Community: San

My specs never told me what to do next, so I built my own SDD harness

San — Sun, 11 Oct 2026 06:43:11 +0000

I do spec-driven development with an AI agent. I tried some well-known spec-driven harnesses, then built my own tool, and for months now I have used only that. This post explains why I needed my own tool and when it is useful.

Repo: https://github.com/opellen/opengoal

The question my specs did not answer

Like many developers who got hooked on AI coding, I was working on several projects at the same time, like crazy. At some point I felt the need for spec-driven development, so I used the well-known harness frameworks. But I ran into a bottleneck:

"What do I do next?"

The specs did not tell me what to do next.

As a workaround, I made a page for each project in Notion and managed things there. But it was a separate place from the project, so keeping it up to date was a hassle. So I wanted state management that lives inside the project.

Why I built my own

My SDD harness started in a hobby project: reverse engineering a game. Reverse engineering takes a lot of analysis and design over many sessions, and designs and plans get overturned all the time. Each time, brainstorming with the AI harness again and rewriting the spec was too much work. If that process runs through a CLI, it is even less agile. I thought about editing the prompts of the existing harnesses, but then I could not keep up with their updates. So I also wanted the prompts of my own harness to be extendable, in a way similar to Jekyll.

There were a few more reasons.

The AI sometimes ignored the later part of a slash command in a harness. I learned that the cause was long text written in a prose-like natural language style. So I started to optimize the prompts. I based this on research showing that pseudocode-style prompts are followed better than natural language and use fewer tokens.

EMNLP 2023: pseudocode-style prompts improved F1 scores by 7 to 16 points over natural language.
CodeAgents (2025): writing agent workflows in pseudocode reduced token use by 55 to 87% and improved performance by 3 to 36 points.

Forced strict TDD was another reason. Small tasks got the same strict TDD as big ones, and if errors still remained, I had to run the process again. The tokens burned for nothing that way were painful.

One question, one file

My harness is based on one rule: one question, one file. If you want to ask the project something, the answer is in exactly one file.

ROADMAP.md  ─────────────  where am I in the big picture?
     CONTEXT.md  ────────  what is this project?
            ● GOAL.md  ──  what do I do now?

This structure is kept in the docs folder by default. You can also choose another location.

Some harness frameworks have a similar structure. But my harness, OpenGoal, does not use a CLI or hooks. It is plain markdown. Nothing extra is added at runtime, so it runs light. I mostly use it in Claude Code, but it can be installed into about 20 tools, including Cursor and Codex.

Spec-driven harness frameworks expect a carefully structured spec, but that can be too much for small tasks. So OpenGoal can create just a goal. You can split that goal into smaller pieces as far as you need, and for simple work you can skip the design document. I did not throw specs away. I write them to fit the size of the task, and GOAL.md is the spec that answers "what do I do next?"

How I use it

When OpenGoal is not set up in a project yet, or when I want to discuss something with the AI, I start with scout.

You: /opgl:scout
AI:  Found an existing codebase. No CONTEXT.md yet.
     Set up project context with `/opgl:context`?

You: /opgl:context init
AI:  ✓ docs/CONTEXT.md created
     To set a goal: `/opgl:goal init`

When the discussion has given enough context about the goal, I ask it to write the goal like this.

You: /opgl:goal init Migrate auth module from JWT to session-based
AI:  ✓ docs/GOAL.md created (5 tasks)

Then the AI may recommend breaking the goal down further, writing a design document, or, for simple work, starting right away without a design document.

AI:  Recommend `/opgl:goal breakdown` — the tasks contain several hidden steps.
AI:  Recommend `/opgl:design init` — implementation task with file-level decisions.
AI:  Recommend `/opgl:go` — this is a simple task.

When the work needs a design, the design document comes first. In OpenGoal, this document works as the spec for a unit of work.

You: /opgl:design init
AI:  ✓ docs/DESIGN.md created
     Session store selection, migration strategy, rollback plan included

During the work, when there is an important decision, it asks for my opinion.

You: /opgl:go
AI:  Task 1/5: Set up session store... ✓ done
     Task 2/5: Replace middleware... ✓ done
     Task 3/5 requires DB schema changes. Proceed?

When you want to handle longer-term goals, you can write a roadmap.

You: /opgl:roadmap init
AI:  ✓ docs/ROADMAP.md created
     ├── M1: Auth migration
     ├── M2: Rate limiting
     └── M3: API versioning

Finishing and pausing a goal

When all the tasks of a goal are done, I archive it. /opgl:goal archive moves GOAL.md and DESIGN.md, and PLAN.md and CHECKPOINT.md if they exist, into docs/archive/goals/. If there is a roadmap, its milestone is marked done too.

An archived goal is still used after that. When I later fix that part or work on the next goal, the AI finds the design, decisions, and checkpoints from that time in the archive and uses them as context. OpenGoal does not read the archive automatically. The archive stays in a fixed place, and CONTEXT.md or the next goal's documents often point to it, so the AI finds and reads it when needed.

You can save the state of a goal in progress as a checkpoint. I mostly use checkpoints to prepare for compaction, or to hand work over to another session or another AI tool. A checkpoint often keeps details that the compaction summary misses. Compaction shrinks the whole conversation at once, but a checkpoint writes down what the AI has found so far and the next steps separately.

You: /opgl:goal checkpoint
AI:  ✓ docs/CHECKPOINT.md saved
     (If the session drops, the next one picks up where you left off)

Checkpoints are especially useful when you use several AI tools together. I subscribe to Claude Code, Codex, and Antigravity, and I use them together. When I write a checkpoint in Claude Code, move to Codex and just run /opgl:go, the work continues where it stopped.

Natural language and other features

You do not have to type the commands every time. When the context is clear, natural language works too. You can answer a recommended command with "ok" or "go", "proceed with task 6" runs /opgl:go, and "save progress" runs /opgl:goal checkpoint.

Beyond that, through my long dogfooding, OpenGoal came to handle suspending and resuming goals, sub-goals, a backlog, and so on. I squeezed as much as I could out of markdown alone.

Token use

Overall, OpenGoal was also designed to reduce the use of our precious tokens. CONTEXT.md plays an important part in that. The AI knows in advance where things are, so there are fewer tool calls, and it needs to re-explore the codebase less at the start of each session. Also, there are no hooks or MCP servers, so unused tool definitions do not take up tokens. The subagent skill that installs with it serves the same purpose. The main agent decides, by the difficulty of the task, which model to hand a subagent, and it makes very small fixes itself. Subagents gather the material for analysis, but the main agent does the analysis itself. I had the problem in other harnesses where the main agent lost the fine details of the context.

Why markdown alone

The biggest reason I built OpenGoal was this thought: all this machinery, built for a perfection we want to rely on, might become mostly unnecessary as AI improves quickly, and then markdown alone might be enough. And I think that has happened. I have finished various projects with only OpenGoal, from a small Obsidian plugin, to a native mobile editor with Notion-style block editing, to a state machine designer.

Using subagents as parallel perspectives on design decision

San — Mon, 13 Apr 2026 13:43:28 +0000

Most of us use Claude Code subagents for parallel work — search this,
refactor that, concurrent execution. Lately I've been using them for
something different: parallel perspectives on the same problem.

If you've discussed design decisions with the main agent long enough, you've hit this: the agent gets buried in the context, or the conversation grows long and it just starts agreeing with you. Either way, fresh angles stop coming.

Subagents don't share that context. They come in cold — no history of the conversation, no accumulated framing — and that's exactly why they work here.

The pattern

The trigger for me was designing the commands for a lightweight AI harness called Scaff I've been building as a side project.

I'd frequently hit walls while discussing the design with the main agent. When I asked for its take, it either couldn't break out of the framing it had built up so far, or it just drifted toward accommodating whatever I wanted.

So I asked the main agent to do this:

"Log the current discussion to docs/discussion/<topic>.md."
"Spawn 3 subagents with different perspectives — LLM, software architect, end-user. Write each take to ...-round-1-<perspective>.md."

This produces:

   docs/discussion/<topic>-round-1-llm.md
   docs/discussion/<topic>-round-1-architect.md
   docs/discussion/<topic>-round-1-enduser.md

Resume the discussion with the main agent using the round-1 files as fresh inputs.
If it converges, ask the main agent to update the original topic doc.
If open issues remain, repeat the same cycle as ...-round-2.md, ...-round-3.md — until it actually closes.

Three perspectives

The key is the three parallel perspectives in step 2.

LLM perspective: "Is this easy for the model to parse?"
Architect perspective: "Will this design still hold up in a year?"
End-user perspective: "Can I understand this in five minutes?"

The three subagents come at the problem from genuinely different angles. More detail below.

The side effect is great too.

The ...-round-1.md, ...-round-2.md files persist as files, so the discussion doesn't evaporate from the conversation — it accumulates as documentation. Three days later when you ask "wait, why did I settle on this?" — the answer is right there.

Leaving a trace of decisions — that alone makes the pattern worth using.

How it played out

Here's how it played out on one design question. I can't include everything, but I've excerpted the moments that were most interesting.

Topic: Should we introduce a separate command for loading OVERVIEW.md?

User: What if the /scaff:scout command auto-loaded OVERVIEW.md — a project-level overview doc — on every session start? What do you think?

Main agent: Good direction. Having the overview available from the start would give better architectural grounding for every task.

User: But scout is often the starting point for a work session, and OVERVIEW.md can get long. End users might feel Scaff is heavier than its philosophy suggests. What about a dedicated /scaff:overview load so it's only pulled in when needed?

Main agent: Good point. A /scaff:overview load subcommand that loads on demand would help save tokens.

User: But for most other commands that work fine without it, that's extra token cost.

Main agent: If we just give /scaff:scout an affordance — let it know docs/OVERVIEW.md exists and let the agent decide whether to read it — that would solve the unnecessary token cost.

User: But in my experience, the LLM will be biased toward reading OVERVIEW.md anyway.

User: Let's hear from the subagents. Log the current discussion to docs/discussion/<topic>.md. Then spawn LLM / software architect / end-user subagents and write each take to ...-round-1-<perspective>.md.

LLM perspective

The bias is real, and the user has correctly diagnosed it. LLMs trained on helpfulness are systematically biased toward "more context = better answer." The model's internal cost function treats a false negative (missed read) as far more painful than a false positive (unnecessary read). Skipping feels like negligence, reading feels like diligence.

(...it walked through concrete examples and estimated the soft rule would fire on 6–8 out of 10 typical invocations.)

Gating must key off literal tokens in the user's input, not the model's interpretation of task semantics. Interpretation always drifts toward "read more."

Architect perspective

The architect didn't touch execution at all. It went after the document structure: CONTEXT.md is "what's being worked on right now," OVERVIEW.md is "big picture that rarely changes" — but read literally, that's exactly what you'd want at session start.

(...it re-diagnosed this as a definitional collision, not a loading problem.)

If OVERVIEW.md cannot answer "who reads me, when, and why," the fix is to delete the role, not to invent a loader for it.

Same topic, completely different layers. The LLM pointed at execution bias. The architect pointed at "should this document even exist?"

End-user perspective

The end-user perspective came in from yet another angle — user behavior:

A soft rule like "read OVERVIEW.md when the task touches architecture" sounds disciplined on paper, but in practice the LLM's threshold for "touches architecture" is fuzzy and self-serving — when in doubt, it reads.

(...after honestly checking how often users actually ask "what's the big picture?" mid-workflow — rarely — it concluded that frequency doesn't justify automation.)

Reject the soft rule entirely. That phrasing is exactly the fuzzy trigger the user is warning about, and it will collapse into always-load within a week of real use.

What converged

After the three perspectives came back, I resumed with the main agent. The architect's "role collision" diagnosis turned out to be a naming collision — CONTEXT.md's first heading was # Project Overview, which made the two docs look like they overlapped. Renaming it to # Working Context fixed it. Subagents can misdiagnose too, but even that surfaced the real issue.

The soft rule was scrapped. All three perspectives rejected it, and I agreed. OVERVIEW.md loading switched to reactive triggers — it only suggests loading when specific events fire, not on every session. The user decides.

Then a new problem: where does this reactive-trigger principle live? The main agent suggested scaff-subagent, but that skill is specifically for subagent delegation. Deciding when to read OVERVIEW.md is main-agent workflow, not subagent work. So we created the scaff-flow skill.

Once scaff-flow existed, we noticed document sync guidelines scattered across individual command files — when to suggest /scaff:design sync, when to suggest /scaff:context sync — had the same character. Those went into scaff-flow too. In the end, scaff-flow became a collection of principles for the main agent to autonomously drive a scaff project — a skill that should work better as AI improves.

The original discussion was "when should OVERVIEW.md be read?" It ended with a new skill that collects main-agent workflow principles — and should age well as models get better at autonomous decisions.

Scaff is on GitHub if you want to look around.

Building Real-time Web Applications with PynneX and FastAPI

San — Sun, 02 Feb 2025 07:35:23 +0000

Building Real-time Web Applications with PynneX and FastAPI

I've created three examples demonstrating how to build real-time web applications using Python worker threads and event-driven patterns. Rather than fully replacing established solutions like Celery or Redis, this approach aims to offer a lighter alternative for scenarios where distributed task queues may be overkill. No locks, no manual concurrency headaches — just emitters in the worker and listeners on the main thread or other workers.

Why PynneX?

While there are several solutions for handling concurrent tasks in Python, each comes with its own trade-offs:

Celery: Powerful for distributed tasks but might be overkill for simpler scenarios
Redis: Great as an in-memory data store, though it adds external dependencies
RxPY: Comprehensive reactive programming but has a steeper learning curve
asyncio.Queue: Basic but needs manual implementation of high-level patterns
Qt's Signals & Slots: xcellent pattern but tied to GUI frameworks

PynneX takes the proven emitter-listener pattern and makes it seamlessly work with asyncio for general Python applications:

Lightweight: No external dependencies beyond Python stdlib
Focused: Designed specifically for thread-safe communication between threads
Simple: Clean and intuitive through declarative event handling
Flexible: Not tied to any UI framework or architecture

For simpler scenarios where you just need clean thread communication without distributed task queues, PynneX provides a lightweight alternative.

🍓 1. Berry Checker (Basic)

A minimal example showing the core concepts:

Worker thread for background processing
WebSocket real-time updates
Event-driven task handling

Demo

View Code

📱 2. QR Code Generator (Intermediate)

Building on the basic concepts and adding:

Real-time image generation
Base64 image encoding/decoding
Clean Controller-Worker pattern

Thread safety comes for free: the worker generates QR codes and emits them, the main thread listens and updates the UI. No manual synchronization needed.

Demo

View Code

📈 3. Stock Monitor (Advanced)

A full-featured example showcasing:

Multiple worker threads
Interactive data grid (ag-Grid)
Real-time charts (eCharts)
Price alert system
Clean architecture

Demo

View Code

Quick Start

Clone repository

git clone https://github.com/nexconnectio/pynnex.git
cd pynnex

Install dependencies

pip install fastapi python-socketio uvicorn

Run any example

python examples/fastapi_socketio_simple.py
python examples/fastapi_socketio_qr.py
python examples/fastapi_socketio_stock_monitor.py

Then open http://localhost:8000 in your browser.

Key Features

Python worker threads for background processing
WebSocket for real-time updates
Event-driven architecture with emitter-listener pattern
Clean separation of concerns
No complex dependencies

Technical Details

PynneX provides a lightweight layer for:

emitter-listener pattern for event handling
Worker thread management
Thread-safe task queuing

Built with:

FastAPI for the web framework
SocketIO for WebSocket communication
Python's built-in threading and asyncio

Learn More

The examples above demonstrate how to build real-time web applications with clean thread communication patterns, without the complexity of traditional task queue systems.