@rafiqui987/markode 0.0.0-stage → 0.2.7

package/templates/method/area-main.md

@@ -0,0 +1,9 @@
+# {{area}}
+
+## Contents
+
+<!-- What this project is, in one or two lines. -->
+
+## Commands
+
+<!-- How to build, run and test this project. -->

package/templates/method/root/docs/tasks/_TEMPLATE.md

@@ -0,0 +1,28 @@
+---
+type: task
+id: <ID>
+status: pending
+area: <area>
+phase: <number>
+depends: []
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <ID> · <Title>
+
+## Goal
+
+<!-- One or two sentences: what is true when this task is done. -->
+
+## Acceptance criteria
+
+- [ ]
+
+## Next step
+
+<!-- One or two actionable lines; a new session starts here. -->
+
+## Log (newest first)
+
+- YYYY-MM-DD: created.

package/templates/method/skills/markode-close-session/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: markode-close-session
+description: Closes a work session in a project that follows the markode method, recording what was done and the next step of every task touched, and updating phases.
+---
+
+# Close the session (markode method)
+
+1. Identify the tasks worked on in this session.
+2. For each one, in its file:
+   - Add a log entry at the top of "Log": date, what was done, key files and decisions.
+   - Rewrite "Next step" in one or two actionable lines (for `blocked`: what it waits on).
+   - Tick the acceptance criteria that are met; set `status` and `updated` in the frontmatter.
+3. If a task is `done`, tick it in its phase (`docs/phases/NN-*.md`). When every task and every item
+   of "Definition of done" is ticked, set the phase to `status: done`; when the first task starts,
+   set it to `in-progress`. Update `updated`.
+4. If an architecture decision was made or changed, update it in its one place (the project's
+   `docs/ARCHITECTURE.md` or the root `docs/architecture/`; create it from the `markode-method`
+   templates if it doesn't exist yet), never in the main doc.
+5. Run `/markode sync` (the docs check of the `markode` skill) and fix what it reports.
+6. Summarize for the user in three lines: what was done, the next step, and anything open.

package/templates/method/skills/markode-method/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: markode-method
+description: Where each kind of project knowledge goes in the markode method (vision, architecture, phases, tasks), when to create each doc, and templates for them. Use before creating, moving or growing a doc under docs/, or when a decision, a goal or a milestone needs writing down.
+---
+
+# The markode method
+
+The docs are a **map and a memory**, not an encyclopedia. Write only what nobody can learn from the
+code: decisions and their reasons, conventions that aren't visible, and the state of the work. The main
+doc (`CLAUDE.md` or `AGENTS.md`) is the map: it says where things are, never what they say.
+
+## Where things go
+
+| What | Where | Create it when |
+|---|---|---|
+| Vision | `docs/vision.md` | the user says what the project is for, for whom, or what is out of scope |
+| Shared architecture | `docs/architecture/<topic>.md` | a technology or design decision affects the whole repository (or several projects) |
+| Architecture of one project (monorepo) | `<project>/docs/ARCHITECTURE.md` | a decision affects only that project |
+| Phases | `docs/phases/NN-name.md` | the user plans a milestone made of several tasks |
+| Tasks | `docs/tasks/<ID>-slug.md`, or `<project>/docs/tasks/` in a monorepo | the user asks for one (`/markode-new-task`) |
+
+A task's status lives only in its frontmatter: there is no index to keep in sync. `/markode-status` and
+the markode Dashboard list tasks by status.
+
+To create one, copy its template from `templates/` next to this file (`vision.md`,
+`architecture-topic.md`, `project-architecture.md`, `phase.md`), replace the `<placeholders>` and set
+`updated` to today. When `docs/architecture/` gets a second file, add a `README.md` there with one line
+per file.
+
+## By kind of project
+
+The main doc says what kind of project this is ("This project", or the "Kind" column of the "Projects"
+table) and where that kind's docs go. Follow it; these are the usual ones:
+
+| Kind | Docs it needs (created when there is something to write) |
+|---|---|
+| App | vision, architecture by topic, phases |
+| Library / package | public API and versioning (`docs/architecture/api.md`); `CHANGELOG.md` if published; phases only for planned milestones |
+| Microservices | contracts (APIs, events) as shared architecture (`docs/architecture/contracts.md`); a contract change gets a task in every consumer |
+| Mobile app | release and store decisions (`docs/architecture/releases.md`) |
+| Data / ML | datasets: source, location, schema (`docs/architecture/data.md`); an experiment log |
+| Infrastructure | environments, one runbook per operation (`docs/runbooks/`) |
+
+If the main doc lists "Existing docs", they are the official ones: update them instead of creating
+new docs that would repeat them.
+
+## What not to write
+
+- What the code already says: folder listings, dependency lists, what a function does.
+- Generic advice ("write clean code", "handle errors properly").
+- The same fact twice: link to the one place where it lives.
+- Empty sections or docs "to fill later": create a doc when there is something real to put in it.
+- Decisions or task lists in the main doc: it only points to them.
+
+## Task statuses
+
+| status | meaning |
+|---|---|
+| `pending` | defined, not started |
+| `in-progress` | being worked on; a new session resumes from its "Next step" |
+| `blocked` | waiting on something; "Next step" says what |
+| `done` | every acceptance criterion is met |
+
+## Phases
+
+- A phase lists its tasks as a checklist; tick a task there when it becomes `done`.
+- `status: in-progress` when its first task starts; `done` when every task and every item of
+  "Definition of done" is ticked.

package/templates/method/skills/markode-method/templates/architecture-topic.md

@@ -0,0 +1,12 @@
+---
+type: architecture
+updated: YYYY-MM-DD
+---
+
+# <Topic>
+
+| Topic | Decision | Why |
+|---|---|---|
+| | | |
+
+<!-- Optional: a ```mermaid flow or a ```tree of the parts this decision shapes. Only what the code doesn't show. -->

package/templates/method/skills/markode-method/templates/phase.md

@@ -0,0 +1,22 @@
+---
+type: phase
+phase: <N>
+status: pending
+updated: YYYY-MM-DD
+---
+
+# Phase <N> · <Name>
+
+## Goal
+
+<!-- One or two sentences: what works at the end of this phase. -->
+
+## Tasks
+
+Tick a task here when its status becomes `done`.
+
+- [ ] [<ID>](<relative path to the task>) <title>
+
+## Definition of done
+
+- [ ]

package/templates/method/skills/markode-method/templates/project-architecture.md

@@ -0,0 +1,14 @@
+---
+type: architecture
+area: <project folder>
+updated: YYYY-MM-DD
+---
+
+# <project> · Architecture
+
+Decisions that only affect this project. Decisions shared with other projects live in the root
+`docs/architecture/`.
+
+| Topic | Decision | Why |
+|---|---|---|
+| | | |

package/templates/method/skills/markode-method/templates/vision.md

@@ -0,0 +1,22 @@
+---
+type: vision
+updated: YYYY-MM-DD
+---
+
+# Vision
+
+## What
+
+<!-- One paragraph: what the project is. -->
+
+## For whom
+
+<!-- Who uses it and what problem it solves for them. -->
+
+## Goals
+
+- <!-- A measurable outcome, e.g. "a new order takes under a minute" -->
+
+## Out of scope
+
+- <!-- What this project will not do, to keep it focused -->

package/templates/method/skills/markode-new-task/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: markode-new-task
+description: Creates a task file in this project's docs (the markode method) when the user asks for a new task. Uses the task template and the next ID of the project, and adds the task to its phase.
+---
+
+# New task (markode method)
+
+Create tasks only when the user asks; you may propose them first.
+
+1. Gather what is missing, in one question: title, goal, project (in a monorepo: the "Projects" table
+   in the root main doc lists them and their prefixes), phase, and dependencies.
+2. Folder and prefix: the project's `docs/tasks/` with its prefix; tasks across projects, or in a
+   single project, go in the root `docs/tasks/` with the prefix the root main doc gives (`T` by default).
+3. Next ID: the highest `<PREFIX>-NNN` in that folder + 1, three digits.
+4. Copy the root `docs/tasks/_TEMPLATE.md` to `<folder>/<ID>-<short-slug>.md`. Fill the frontmatter
+   (`id`, `status: pending`, `area`, `phase`, `depends`, `created` and `updated` = today), the title,
+   the goal and the acceptance criteria as a checklist. The frontmatter is the only place the status
+   lives: there is no task index to update.
+5. If it belongs to a phase, add `- [ ] [<ID>](<relative path>) <title>` under "Tasks" in
+   `docs/phases/NN-*.md` (create the phase from the `markode-method` template if the user is planning
+   a new one).
+6. Show the task to the user. Do not start working on it until they say so.

package/templates/method/skills/markode-status/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: markode-status
+description: Summarizes where the work stands in a project that follows the markode method - what was touched last, what is in progress, blocked and pending - grouped by project in a monorepo. Use when the user asks what is pending, where things stand, what is left, or what was done last time.
+---
+
+# Status (markode method)
+
+Answer from the task files, not by exploring the code.
+
+1. **Task folders**: `docs/tasks/` and, in a monorepo, each `<project>/docs/tasks/` from the "Projects"
+   table of the root main doc. Read only each file's frontmatter (`id`, `status`, `phase`, `depends`,
+   `updated`) and its title; skip `_TEMPLATE.md`. For example:
+   `grep -H -E "^(id|status|phase|depends|updated):|^# " docs/tasks/*.md apps/*/docs/tasks/*.md`
+2. **Last session**: the tasks with the most recent `updated`. If git is available, also
+   `git log --since=<that date> --name-only --format="%h %s"` to see which projects changed, including
+   changes no task covers.
+3. **Next steps**: for `in-progress` and `blocked` tasks only, read their "Next step" section.
+4. **Answer** in this order, grouped by project (shared work first), one line per task:
+   - **Last session**: the projects and tasks touched.
+   - **In progress**: `ID · title` — next step.
+   - **Blocked**: `ID · title` — what it waits on.
+   - **Pending**: how many; list the next ones (lowest phase first) whose `depends` are all `done`.
+   - **Without a task**: recent changes no task covers, if any.
+5. Don't open other docs unless the user asks to go deeper. End by asking which task to continue.

package/templates/proposals/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: markode-proposals
+description: Write temporary proposals the user answers in markode (options with ASCII or Mermaid diagrams, choices to tick, comments like in Word), then apply their answer to every affected doc and delete the proposal. Use when an answer would be long or has options or a design to validate, when the user asks for a proposal, or when they say a proposal is answered.
+---
+
+# Proposals (markode)
+
+A proposal is a **temporary** file for one decision. Write one instead of a chat answer when:
+
+- the answer would be long, or has several options, diagrams or a design to validate; or
+- the user asks for a proposal.
+
+For a short answer or a single obvious option, just answer in the chat.
+
+After writing the file:
+
+1. If a task waits on this decision, set it to `status: blocked` with "Next step: waiting on proposal
+   <path>".
+2. Start `markode wait <path>` **in the background** (in Claude Code, a background Bash command: you are
+   notified when it exits). It waits, without using tokens, until the user presses "Done, send my
+   answer" in markode, then prints their answer: choices, open questions, comments waiting for a reply,
+   affected docs and your "After your answer" list. If you can't run background commands, skip it: the
+   user will tell you, or the next `/markode sync` finds the answered proposal.
+3. Tell the user the path in one line and that you will continue when they answer. Meanwhile, keep
+   working on anything that doesn't depend on the decision.
+
+When the watcher's output arrives, go straight to "When the user answers". Once applied, the decision
+lives in the docs it affects and the proposal is deleted.
+
+## Where
+
+{{where}}.
+
+## Format
+
+````md
+---
+type: proposal
+status: open          # open → answered (set by the user in markode); deleted once applied
+updated: YYYY-MM-DD
+affects: [docs/tasks/T-004-login.md, docs/architecture/auth.md]   # docs the decision will change
+---
+
+# Proposal: <topic>
+
+## Context
+
+<!-- Two or three lines: what needs deciding and why now. -->
+
+## Option A: <name> (recommended)
+
+```text
+ Browser ──REST──▶ Gateway ──gRPC──▶ Users ──▶ (Postgres)
+```
+
+What it means, pros and cons in a few bullets.
+
+## Option B: <name>
+
+```mermaid
+flowchart LR
+  Browser --> Users --> DB[(Postgres)]
+```
+
+## Your choice
+
+<!-- choose: one -->
+- [ ] A: <name>
+- [ ] B: <name>
+
+## Also include
+
+- [ ] <optional extra the user can tick>
+
+## After your answer
+
+- <what you will do with each possible choice, so any session can continue from here>
+
+## Open questions
+
+1. <question>
+
+   <!-- choose: one -->
+   - [ ] <answer>
+   - [ ] <answer>
+````
+
+- Diagrams: a ` ```text ` block with box-drawing characters for small sketches, ` ```mermaid ` for
+  flows and sequences. markode renders both.
+- In ASCII diagrams use only single-width characters (box drawing `┌─┐│└┘▶`, letters, `#`, `-`); shading
+  blocks like `▓░` are wider in many fonts and break the alignment.
+- `<!-- choose: one -->` right before a checklist makes it single choice in markode (radio buttons);
+  without it, any number can be ticked.
+- Put your recommendation first and say why.
+
+## Comments
+
+The user comments like in Word. A comment is an HTML comment right after the block it refers to,
+indented like that block (inside a list item: aligned with the item's text):
+
+```md
+- [x] A: gateway validates
+  <!-- comment by Rafael, 2026-10-22, on "gateway validates": What if the gateway goes down? -->
+```
+
+Answer each comment with a reply right below it (or below the last reply), same indentation:
+
+```md
+  <!-- reply by AI, 2026-10-22: Two Cloud Run instances minimum; added to the architecture. -->
+```
+
+Never delete or rewrite the user's comments: they resolve them in markode. Never put `-->` inside a
+comment's text.
+
+- `affects`: the docs that depend on this decision (tasks, phases, architecture, vision, other
+  proposals…), so the user sees what their choice will change.
+
+## When the user answers
+
+1. Read the ticked options, the open questions and every comment without a reply from you.
+2. If something is unclear or a comment raises a new question, reply to that comment, set
+   `status: open` again, tell the user what you need, and start `markode wait` again. Don't apply
+   anything yet.
+3. Otherwise apply the decision to every doc that depends on it: the ones in `affects` and any other
+   you find (a task's goal or acceptance criteria, a phase's task list, an architecture table, the
+   vision…). Record it in its one place: in the markode method, the architecture file for design
+   decisions, and a line in the log of the task it belongs to (`<date>: decided <what> (proposal
+   <name>)`).
+4. Delete the proposal file: it was temporary, the decision now lives in those docs. A task that was
+   `blocked` on it goes back to `in-progress`, with its next step from your "After your answer" list.
+5. Tell the user in a few lines what you changed and where, then continue with that task.

package/templates/rules/ask-before-commit.md

@@ -0,0 +1,4 @@
+---
+title: Ask before committing
+---
+- Never commit, push or open pull requests without asking first.

package/templates/rules/ask-new-dependencies.md

@@ -0,0 +1,4 @@
+---
+title: Ask before adding dependencies
+---
+- Don't add, remove or upgrade dependencies without asking; prefer what the project already uses.

package/templates/rules/ask-when-unclear.md

@@ -0,0 +1,4 @@
+---
+title: Ask when unclear
+---
+- If a requirement is ambiguous, ask instead of guessing; state your assumptions when you proceed.

package/templates/rules/match-conventions.md

@@ -0,0 +1,4 @@
+---
+title: Follow the project's conventions
+---
+- Read the surrounding code first and match its style, naming, patterns and libraries.

package/templates/rules/minimal-changes.md

@@ -0,0 +1,4 @@
+---
+title: Minimal, focused changes
+---
+- Change only what the task needs: don't refactor, rename or reformat unrelated code.

package/templates/rules/protect-secrets.md

@@ -0,0 +1,4 @@
+---
+title: Protect secrets
+---
+- Never read, print or commit secrets, `.env` files or credentials; use the existing configuration mechanism.

package/templates/rules/tests-with-changes.md

@@ -0,0 +1,4 @@
+---
+title: Tests with every change
+---
+- Add or update tests for every behavior you add or change; never delete or skip a failing test to make it pass.

package/templates/rules/update-docs.md

@@ -0,0 +1,4 @@
+---
+title: Keep docs up to date
+---
+- When behavior, commands or configuration change, update the docs that describe them in the same change.

package/templates/rules/verify-before-done.md

@@ -0,0 +1,4 @@
+---
+title: Verify before saying it's done
+---
+- Run the tests, the linter and the type checker before saying a task is done, and report any failure with its output.

package/templates/sdd/openspec/openspec/README.md

@@ -0,0 +1,89 @@
+# OpenSpec guide
+
+This project uses [OpenSpec](https://github.com/Fission-AI/OpenSpec): agree on **what** to build in
+Markdown before writing code, so you and the AI work from the same spec.
+
+## Structure
+
+```tree
+openspec/
+  config.yaml          # project context and rules for the AI (edit in your code editor)
+  specs/               # how the system behaves TODAY, one folder per domain
+    auth/
+      spec.md
+  changes/             # proposed work, one folder per change
+    add-2fa/
+      proposal.md      # why and what
+      design.md        # how (optional, for non-trivial changes)
+      tasks.md         # checklist the AI works through
+      specs/auth/spec.md   # delta: requirements added, modified or removed
+    archive/           # finished changes, dated
+```
+
+## Lifecycle
+
+```mermaid
+flowchart LR
+  Propose[Propose a change] --> Review[Review proposal, specs and tasks]
+  Review --> Apply[Apply: implement the tasks]
+  Apply --> Archive[Archive: deltas merge into specs/]
+```
+
+| Step | Command (if OpenSpec is installed) | Or ask the AI |
+|---|---|---|
+| Explore an idea | `/opsx:explore` | "Let's think through X before proposing anything." |
+| Propose | `/opsx:propose add 2FA` | "Create an OpenSpec change `add-2fa` with proposal, tasks and spec deltas." |
+| Implement | `/opsx:apply` | "Implement the tasks of `add-2fa`, ticking each one." |
+| Finish | `/opsx:archive` | "Archive `add-2fa` and merge its deltas into `openspec/specs/`." |
+
+## Examples
+
+**`changes/add-2fa/proposal.md`**
+
+```md
+# Proposal: Add two-factor authentication
+
+## Why
+Accounts are protected by a password only.
+
+## What changes
+- Users can enable TOTP codes from their settings.
+- Login asks for the code when 2FA is enabled.
+
+## Out of scope
+- SMS codes.
+```
+
+**`changes/add-2fa/specs/auth/spec.md`** (delta)
+
+```md
+## ADDED Requirements
+
+### Requirement: Two-factor login
+The system SHALL ask for a one-time code after the password when 2FA is enabled.
+
+#### Scenario: Valid code
+- **WHEN** the user enters a valid code
+- **THEN** they are logged in
+```
+
+**`changes/add-2fa/tasks.md`**
+
+```md
+## 1. Backend
+- [ ] 1.1 Store the TOTP secret per user
+- [ ] 1.2 Verify codes on login
+
+## 2. Frontend
+- [ ] 2.1 Settings screen to enable 2FA
+```
+
+## Installing OpenSpec
+
+The `/opsx:*` commands come from the OpenSpec CLI. If they are missing, install it (needs Node.js) and
+run its setup here; it keeps the files you already have:
+
+```bash
+npm install -g @fission-ai/openspec
+openspec init
+```

package/templates/sdd/openspec/openspec/config.yaml

@@ -0,0 +1,12 @@
+schema: spec-driven
+
+# Project context (optional): constraints an agent can't infer from the code.
+# context: |
+#   Designs and tasks must cover Windows, macOS and Linux
+
+# Per-artifact rules (optional).
+# rules:
+#   proposal:
+#     - Always state what is out of scope
+#   tasks:
+#     - Break tasks into chunks of at most 2 hours

package/templates/sdd/speckit/.specify/memory/constitution.md

@@ -0,0 +1,30 @@
+# [PROJECT_NAME] Constitution
+
+<!-- The principles every feature must respect. Fill it in, or run /speckit-constitution and let the AI
+     draft it from a conversation. Replace every [PLACEHOLDER]. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Test-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Tests are written and approved before the implementation. -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. Simplicity -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Start with the simplest thing that works; no speculative abstractions. -->
+
+### [PRINCIPLE_3_NAME]
+[PRINCIPLE_3_DESCRIPTION]
+
+## Constraints
+
+[CONSTRAINTS]
+<!-- Example: TypeScript only; Postgres; must run on Node 20+. -->
+
+## Governance
+
+This constitution overrides other practices. Amendments are documented here with their reason.
+
+**Version**: 1.0.0 | **Ratified**: {{date}} | **Last amended**: {{date}}

package/templates/sdd/speckit/specs/README.md

@@ -0,0 +1,82 @@
+# Spec Kit guide
+
+This project uses [GitHub Spec Kit](https://github.com/github/spec-kit): every feature goes from an
+idea to a spec, a plan and a task list before any code is written.
+
+## Structure
+
+```tree
+.specify/
+  memory/constitution.md   # principles every feature must respect
+  templates/               # templates the commands fill (installed by Spec Kit)
+specs/
+  001-user-login/          # one folder per feature, numbered
+    spec.md                # what and why: user stories, requirements
+    plan.md                # how: stack, architecture, data model
+    tasks.md               # ordered checklist, by user story
+    research.md            # optional: findings behind the plan
+    data-model.md          # optional
+    contracts/             # optional: API definitions
+```
+
+## Flow
+
+```mermaid
+flowchart LR
+  C[Constitution] --> S[Specify] --> Q[Clarify] --> P[Plan] --> T[Tasks] --> I[Implement]
+```
+
+| Step | Command (if Spec Kit is installed) | Or ask the AI |
+|---|---|---|
+| Principles | `/speckit-constitution` | "Fill `.specify/memory/constitution.md` with our principles." |
+| Spec | `/speckit-specify users can log in with email` | "Write `specs/001-user-login/spec.md`: user stories, requirements, success criteria. No tech choices." |
+| Clarify (optional) | `/speckit-clarify` | "Ask me about anything ambiguous in the spec." |
+| Plan | `/speckit-plan use Next.js and Postgres` | "Write `plan.md` for 001 with the stack and data model." |
+| Tasks | `/speckit-tasks` | "Break the plan into `tasks.md`, grouped by user story." |
+| Build | `/speckit-implement` | "Implement the tasks of 001 in order, ticking each one." |
+
+## Examples
+
+**`specs/001-user-login/spec.md`**
+
+```md
+# Feature Specification: User login
+
+## User Scenarios
+
+### User Story 1 - Log in with email (Priority: P1)
+A registered user logs in with email and password to reach their dashboard.
+
+**Acceptance Scenarios**:
+1. **Given** a registered user, **When** they enter valid credentials, **Then** they see their dashboard.
+2. **Given** a wrong password, **When** they submit, **Then** they see an error and stay logged out.
+
+## Requirements
+- **FR-001**: The system MUST lock an account after 5 failed attempts.
+
+## Success Criteria
+- **SC-001**: 95% of logins complete in under 2 seconds.
+```
+
+**`specs/001-user-login/tasks.md`**
+
+```md
+## Phase 1: User Story 1 - Log in with email (P1)
+- [ ] T001 [US1] Create the users table in src/db/schema.ts
+- [ ] T002 [P] [US1] Login form in src/app/login/page.tsx
+- [ ] T003 [US1] POST /api/login in src/app/api/login/route.ts
+```
+
+`[P]` marks tasks that can run in parallel.
+
+## Installing Spec Kit
+
+The `/speckit-*` commands come from the Spec Kit CLI, which needs [uv](https://docs.astral.sh/uv/)
+(Python). If they are missing:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh     # install uv
+uvx --from git+https://github.com/github/spec-kit.git specify init --here --integration claude
+```
+
+It keeps the files you already have, including the constitution.