nobrainer-tech-flow 0.0.0-stage → 2.4.1

package/skills/nobrainer-wiki/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: nobrainer-wiki
+description: "Use when the owner says nb-wiki, nb-add, nb-get, nb-tidy, or llm-wiki; asks to create or query a wiki, save durable knowledge, or safely audit and maintain a Markdown knowledge base across projects or sessions; do not use for transient task state."
+---
+
+# NoBrainer Wiki
+
+Build and use a small, trustworthy knowledge system only when information should
+compound across tasks. This skill is explicitly inspired by Andrej Karpathy's
+[LLM wiki concept](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+and is an independent portable adaptation, not an official Karpathy project.
+
+Read [references/setup.md](references/setup.md) before creating or reconnecting a
+wiki. One skill owns all wiki behavior so setup, query, capture and maintenance
+cannot drift into competing wrappers.
+
+## Select one mode
+
+- `SETUP`: decide whether a wiki is justified, then create/connect/govern it.
+- `GET`: read-only targeted retrieval. This is the default for a question.
+- `ADD`: explicit ingestion or promotion of durable knowledge.
+- `TIDY_AUDIT`: inspect trust, links, freshness and backlog without writing.
+- `TIDY_APPLY`: apply only deterministic approved maintenance after an audit.
+
+Do not combine modes invisibly. A `GET` that discovers a durable insight does
+not authorize `ADD`; a tidy audit does not authorize semantic rewrites.
+
+## Decide whether a wiki is justified
+
+Prefer normal repository documentation when knowledge is local to one codebase
+and already discoverable. A wiki is justified when durable decisions, sources,
+research, explicit owner preferences or operational knowledge must be queried
+across tasks/sessions and would otherwise be repeatedly reconstructed.
+
+Do not store live execution state, leases, current hashes, transient blockers,
+credentials or secrets. A spec defines a contract; a plan orders work; a wiki
+preserves reusable knowledge. One fact has one canonical owner.
+
+## Shared safety and knowledge contract
+
+Resolve the wiki root from project instructions or the owner; never guess a
+destination. Read its rules, index, classification boundary, relevant pages and
+dirty/writer state before any operation.
+
+Classify source and destination:
+
+- `PUBLIC`: safe for intentional disclosure;
+- `INTERNAL`: non-public operating knowledge without restricted personal data;
+- `CONFIDENTIAL`: explicitly restricted, minimum necessary content;
+- `SECRET`: credentials, keys, tokens, cookies, seed phrases or equivalents.
+
+Never write `SECRET` material to source captures, pages, inboxes, logs, prompts
+or Git history. Never promote private personalization into a public repository.
+Respect copyright/access constraints and prefer concise synthesis plus provenance
+over copying an external work.
+
+Separate observed fact, attributed claim, inference, recommendation and
+forecast. Every durable entry needs source, date, scope, classification and
+certainty; dates are absolute. Preserve contradictions and stale-risk markers
+rather than silently choosing a convenient version.
+
+## `SETUP`
+
+Run a read-only preflight:
+
+- inspect existing instructions, wiki/map/rules, folder conventions and Git
+  state;
+- detect sources/pages/inbox/log, writers, sync and automation;
+- classify the target and compare it with the minimal model in the setup
+  reference;
+- check every managed marker pair and overlapping dirty file.
+
+Create only missing pieces and preserve established conventions. Use one source
+of truth and one inbox per independent writer/machine. Do not initialize a
+repository, pull/rebase, relocate, truncate or overwrite existing content just
+because a template differs. Unknown classification, malformed markers,
+conflicting writer or dirty overlapping scope is `BLOCKED`.
+
+## `GET` — read-only retrieval
+
+1. Rewrite the question into concepts, aliases, languages and freshness needs.
+2. Use the index as a map, then `rg` exact/relevant terms. Follow only useful
+   links and cited sources; do not load the whole vault by default.
+3. Prefer curated pages and inspect raw sources when a claim, conflict or exact
+   wording needs verification.
+4. Enforce the requester's access boundary and redact unsafe paths/details.
+5. Return `WIKI_FACT`, `INFERENCE`, `RECOMMENDATION` and `UNKNOWN` distinctly,
+   with page/source provenance and freshness.
+
+An absent lexical hit is not proof of absence. Search synonyms and related map
+entries before declaring a gap. `GET` never repairs, updates freshness, captures
+the answer, commits or pushes.
+
+## `ADD` — durable capture or promotion
+
+1. Confirm the owner requested persistence or that the project's explicit
+   `LEARNING_WRITE_POLICY: AUTO_SCOPED` covers this durable event, then resolve
+   one writer for the target files.
+2. Read the complete allowed input; record provenance, date, classification and
+   capture method. Keep verbatim source separate from synthesis.
+3. Extract only reusable facts, decisions, definitions, evidence and procedures.
+   Exclude transient status and unsupported conclusions.
+4. Search existing pages by terms/aliases/languages before creating anything.
+5. Prepare one scoped write set: allowed source capture, pages, index, log and
+   exact inbox items to promote.
+6. Apply minimal edits with citations and relative links.
+7. Verify target content, index reachability, source links, classification and
+   secret boundaries before marking inbox items processed.
+8. Append one meaningful change-log entry only after successful promotion.
+
+A mixed sensitive source requires an explicit sanitization list and destination
+approval. Do not mass-rewrite, resolve owner decisions, commit, push or publish
+unless those actions were separately authorized.
+
+For video or recorded-session knowledge, preserve the complete available
+timestamped transcript or caption stream as the raw source before synthesis.
+Keep source capture separate from curated knowledge, cite timestamp ranges, and
+use articles or summaries only as secondary cross-checks. If the complete
+stream is unavailable, mark the capture partial rather than reconstructing
+missing speech from surrounding context.
+
+## `TIDY_AUDIT` and `TIDY_APPLY`
+
+Audit exact dangling links, index drift, stale/time-sensitive claims, uncited
+material claims, contradictions, duplicate candidates, orphans, inbox backlog,
+classification leaks and secret/PII risk. Every finding needs file/line, evidence,
+confidence and one recommended action. An orphan may be intentional; a fuzzy
+title match is not permission to merge.
+
+`TIDY_APPLY` may automatically perform only deterministic reversible work in the
+approved scope: an exact link correction with a proven target, missing index
+link, format normalization, or removal of a processed inbox item whose payload
+is proven present and retention allows removal. Semantic merges, page/source
+deletion, contradiction choice, reclassification and broad rewrites require an
+owner decision. Re-read before each write, rerun checks after, and preserve a
+scoped rollback.
+
+## Durable personalization without hidden memory
+
+Preserve only explicit reusable preferences, corrections, decisions and verified
+working patterns. At task start retrieve only relevant pages; at close capture
+only information likely to matter again. Do not infer a permanent trait from one
+interaction. The owner must be able to inspect, correct and remove personalized
+knowledge.
+
+An external memory or retrieval service must earn its place with a representative
+task set and a measured recall, context and latency target. Before adoption,
+define project/account scope, source provenance, freshness and expiry, conflict
+handling, correction/deletion/export, privacy, cost and a file-readable fallback.
+Treat an injected profile or recalled item as context to verify, never as current
+state or authority. Keep this policy in `nobrainer-wiki`; do not create another
+permanent skill merely for a provider integration.
+
+## Automation and close gate
+
+Manual capture/promotion is the default. Schedule it only when measured volume
+justifies a bounded trigger/input/output, one state owner, idempotence, retry
+budget, conflict stop, secret filtering, dry run, logs and rollback. Scheduler,
+credentials, commit/push and publishing remain owner gates.
+
+Finish with mode, root/classification, exact pages/sources/inbox/log touched,
+provenance, checks, contradictions, omitted sensitive material, uncertainty,
+rollback and one next action. Never claim a clean or synchronized wiki when a
+scan/source was partial or inaccessible.

package/skills/nobrainer-wiki/references/setup.md

@@ -0,0 +1,88 @@
+# NoBrainer Wiki setup reference
+
+Adapt this reference to the target. Existing conventions win when they preserve
+the same safety and information boundaries.
+
+## Minimal layout
+
+```text
+WIKI_ROOT/
+  WIKI.md             durable rules and confidentiality boundaries
+  index.md            small map to curated knowledge
+  log.md              append-only meaningful changes
+  sources/            raw captures with provenance and classification
+  pages/              curated, linked, cited knowledge
+  _inbox/WRITER.md    append-only candidates owned by one writer
+```
+
+Do not create empty layers that have no present use. A project-local wiki may
+live under its existing docs structure.
+
+## Curated page contract
+
+```markdown
+# Human title
+
+One durable statement a future reader can act on.
+
+CLASSIFICATION: PUBLIC | INTERNAL | CONFIDENTIAL
+LAST_VERIFIED: YYYY-MM-DD | UNKNOWN
+
+## Facts
+
+- <observed or source-backed claim> (source: <relative source or URL>)
+
+## Decisions and implications
+
+- <decision, owner, date and scope>
+
+## Contradictions / stale risk
+
+- <conflict or freshness warning, or NONE>
+
+## Related
+
+- [[another-page]]
+```
+
+Use absolute dates. Mark observed fact, inference, recommendation and forecast
+separately. Do not resolve conflicting sources by silently deleting one.
+
+## Managed instruction block
+
+Insert a project-specific block with a complete marker pair. Keep it concise so
+instructions do not become a copy of the wiki protocol.
+
+```markdown
+<!-- NB-WIKI:START -->
+## NoBrainer Wiki
+
+Knowledge root: `WIKI_ROOT`. Rules: `WIKI_ROOT/WIKI.md`.
+- At session start, read `WIKI_ROOT/index.md`, then search only relevant pages.
+- Capture only durable facts in the current writer's inbox; never secrets.
+- Use `nobrainer-wiki` mode `GET` for queries, `ADD` for explicit persistence,
+  and `TIDY_AUDIT` before any maintenance write.
+- Runtime state, leases and transient blockers stay in their canonical ledgers.
+<!-- NB-WIKI:END -->
+```
+
+Before replacement, require exactly one START and one END in the correct order.
+Zero markers means append at the repository's conventional location. Any other
+count/order is a stop for manual repair. Verify a byte-level before/after diff
+outside the managed block.
+
+## Setup report
+
+```text
+WIKI_DECISION: REUSE | CREATE | REPAIR | NOT_JUSTIFIED | BLOCKED
+ROOT: <resolved path/reference>
+CLASSIFICATION: <level>
+FILES_REUSED: <list>
+FILES_CREATED: <list>
+INSTRUCTIONS_UPDATED: <list>
+AUTOMATION: NOT_CONFIGURED | PROPOSED | VERIFIED
+CHECKS: <commands/readbacks>
+UNCERTAINTY: <items or NONE>
+ROLLBACK: <exact procedure and readback>
+NEXT_ACTION: <one action>
+```

package/skills/nobrainer-writing/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: nobrainer-writing
+description: "Use when the owner says nb-write, nb-brief, nobrainer-writing, nobrainer-style, or nobrainer-human-like, or asks for prose quality work on a user-facing artifact, such as drafting, rewriting, compressing, humanizing, editing, or reviewing it; maximize useful information per word without dropping facts, evidence, caveats, voice, or required action."
+---
+
+# NoBrainer Writing
+
+Produce high-signal prose that helps a specific reader understand, decide or act.
+Treat the Pareto idea as a direction: preserve nearly all decision-relevant value
+while using far fewer words. It is not permission to remove evidence, conditions
+or nuance merely to hit an arbitrary ratio.
+
+The protocol, field names and examples in this public skill are written in
+English. Match the requested output language; when English is requested, use
+plain, idiomatic English rather than a literal translation.
+
+This skill owns prose quality. `nobrainer-research` owns missing or current
+external facts, `nobrainer-decide` owns consequential choices, and
+`nobrainer-build` owns behavioral code changes and repository integration. A
+small text-only edit can stay here. Do not invoke this skill for a one-sentence
+answer that is already clear, specific and complete.
+
+Use `BRIEF` for a short actionable artifact: a comment, bug report, feature
+issue, user story, status update or one clear request. It is a mode of this
+skill, not a new skill. Read [references/brief-artifacts.md](references/brief-artifacts.md)
+for the matching shape and examples before drafting.
+
+Read [references/research.md](references/research.md) only when changing this
+protocol, auditing its rationale or comparing another writing method. Ordinary
+writing runs should not spend context on the research record.
+
+## Choose one mode
+
+- `DRAFT`: create prose from an established brief and verified source material.
+- `COMPRESS`: shorten existing prose while preserving its material meaning.
+- `REWRITE`: improve clarity, structure, voice and naturalness without changing
+  the factual contract.
+- `REVIEW`: identify only material prose defects and propose the smallest useful
+  correction; do not rewrite merely to express a preference.
+- `TECHNICAL`: make English procedures or explanations easier to follow. Read
+  [plain technical English](references/plain-technical-english.md) for its two
+  profiles and meaning checks. It is not a certified ASD-STE100 checker.
+- `BRIEF`: create or compress one short actionable artifact. Choose exactly one
+  shape from the reference: `COMMENT`, `BUG`, `ISSUE`, `USER_STORY` or `REQUEST`.
+
+If the user did not name a mode, default to `TECHNICAL` for English technical
+procedures and explanations, including specs and runbooks. For other artifacts,
+infer the smallest mode that satisfies the request. Answer users directly in
+their requested language; keep non-English technical prose clear and natural
+without applying an English dictionary or forcing an intermediate translation.
+Explicit language, format and voice requirements take precedence. A request to "humanize" means `REWRITE`, not detector evasion or the
+injection of fake mistakes.
+
+## Freeze the content contract
+
+Before drafting, resolve internally:
+
+```text
+PURPOSE:
+AUDIENCE:
+USE_AFTER_READING:
+ARTIFACT_AND_CHANNEL:
+LANGUAGE_AND_TONE:
+VOICE_SOURCE: supplied sample | project guide | inferred neutral | NONE
+MUST_PRESERVE: facts | names | numbers | dates | links | quotations | terms |
+               commands | conditions | uncertainty | caveats | requested action
+SOURCE_STATUS: VERIFIED | PROVIDED | RESEARCH_REQUIRED | UNKNOWN
+LENGTH_OR_FORMAT_CONSTRAINT:
+```
+
+Infer obvious fields from the request and current project. Ask one focused
+question only when the answer changes factual meaning, audience fit, material
+tone or safety. In a larger Flow run, use the approved BUDDY brief and do not
+re-open settled requirements.
+
+For `BRIEF`, additionally freeze the observed problem or desired outcome, the
+reader's next action, the smallest useful evidence, and the pass/fail condition
+when one exists. If a missing fact would make the artifact misleading or
+non-actionable, ask one precise question or return `INPUT_REQUIRED`; do not fill
+the gap with a plausible cause, metric, user or environment.
+
+Preserve every material input detail, including onset, negation, current status,
+condition and uncertainty. Do not turn a fear, hypothesis or requested decision
+into an observed fact or an invented acceptance rule. If the desired behavior is
+not specified, keep the decision open or write `UNKNOWN` rather than choosing a
+warning, retry policy, UI state or technical solution.
+
+For `COMPRESS`, `REWRITE` and `TECHNICAL`, make a private meaning ledger before changing the
+text. Track every material claim, number, name, date, URL, quotation,
+attribution, identifier, command, negation, condition, uncertainty marker,
+caveat and call to action. Never add a source, experience, opinion, metric or
+detail that the input does not support. Route a material knowledge gap to
+`nobrainer-research`; do not cover it with fluent prose.
+
+## Write in six passes
+
+1. **Outcome:** state the answer, decision, result or requested action in the
+   first useful sentence. Keep background only when the reader needs it to
+   interpret that outcome.
+2. **Structure:** group each idea once. Put decision-relevant information first.
+   Use headings, bullets or a table only when they make a real relationship
+   easier to scan than short prose.
+3. **Compression:** remove throat-clearing, repeated points, self-reference,
+   empty transitions, generic summaries and decorative detail. Merge sentences
+   only while the result remains easier to understand.
+4. **Precision:** prefer concrete nouns and precise verbs. Name the actor when it
+   clarifies responsibility. Use one term per concept and define necessary
+   jargon for the actual audience.
+5. **Voice:** match an authentic supplied sample or project guide when one
+   exists. Otherwise use a direct, calm and natural neutral voice. Adapt tone to
+   the reader's situation; technical, legal, error and safety text should not be
+   made casual for entertainment.
+6. **Integrity:** compare the final text with the meaning ledger and the user's
+   requested action. Restore anything materially lost, and remove anything that
+   cannot be traced to the input or a cited source.
+
+Compress structure before swapping vocabulary. A shorter synonym cannot repair
+a paragraph with no clear purpose.
+
+For `BRIEF`, put the outcome or failure in the title/first sentence, keep one
+problem or goal per artifact, and include only evidence that changes action or
+triage. Use the fewest applicable fields. A comment is normally a few sentences;
+an issue or story is normally one description, a short evidence/context block and
+two to five testable criteria. Put long logs, transcripts and screenshots after
+the concise core or link them; never hide them when they are needed for proof.
+Return the finished artifact only unless the owner asks for an audit.
+
+For task-shaped `BRIEF` artifacts (`BUG`, `ISSUE`, `USER_STORY` and `REQUEST`),
+write `Description:` and `Definition of Done (DoD):` as explicit fields.
+`Description` states what is wrong, needed or intended; `Acceptance` states
+observable product behavior when applicable; `Definition of Done (DoD)` states
+the closure condition and required proof. Do not hide either field inside a
+generic paragraph or rename DoD to a vague `Done when`. `COMMENT` stays compact
+and does not need task fields.
+
+Number every acceptance criterion with a sequential two-digit ID: `AC01`, `AC02`,
+`AC03` and so on. Start at `AC01`, do not leave gaps, and do not use anonymous
+checkboxes under `Acceptance`; DoD remains a separate section and may reference
+the acceptance IDs.
+
+For both `BUG` and `COMMENT`, always provide one compact `ENV:` block with
+`Name`, `URL` and `User`. `Name` is one of `QA`, `DEV`, `TEST`, `PROD`,
+`PREPROD`, `BETA` or `UNKNOWN`; use `N/A` when a field genuinely does not
+apply. `User` is a role or redacted/synthetic alias, never a credential.
+
+For `BUG`, start with `Description`, then keep the diagnostic fields separate and
+in this order: `ENV:`, `Steps to reproduce`, `Current behavior` and
+`Expected behavior`; follow them with the applicable surface-proof sections:
+`API request (cURL)`, `API response`, `Database query (read-only)`,
+`Database result`, `Evidence` for a UI screenshot or MP4 recording and, only when
+the page-load/request chain matters, `HAR`; finish with `Definition of Done (DoD)`.
+Use `UNKNOWN` when a value is not known; never silently omit a required field or
+invent its value.
+
+For `ISSUE`, keep `Description` to one sentence, then use `Who is affected`,
+`Desired outcome`, `Evidence`, `Acceptance` and `Definition of Done (DoD)` by
+default. Add another field only when it changes triage or implementation.
+
+Surface proof has a copyable artifact shape:
+
+- **API:** put the complete redacted request in a fenced `bash` block as a
+  `curl` command, including method, URL, all captured headers and body. Put the
+  observed response in a separate fenced `http` block with status, all captured
+  headers and body. Redact sensitive values without changing the request's
+  material shape.
+- **Database:** put the read-only query and its result in separate fenced code
+  blocks, using `sql` for the query and the result's actual format when useful.
+  Redact sensitive rows and values.
+- **UI:** put a screenshot or MP4 recording under `Evidence`. If the failure
+  depends on the page-load or request chain, attach a HAR as well; the exact URL
+  and steps still belong in the report.
+
+If several surfaces are involved, include each applicable proof pair or artifact.
+Do not replace the API/DB proof pairs with generic prose. For a UI bug, `Evidence`
+is the attachment field; a URL or prose description alone does not replace it.
+If required proof is missing, return `INPUT_REQUIRED` and name the missing
+artifact instead of drafting a weaker report.
+
+## Anti-slop gate
+
+Remove these patterns when they add no information:
+
+- praise, greetings, apologies or announcements before the actual point;
+- inflated significance, sales language, vague attribution and unsupported
+  certainty;
+- headings that repeat the next sentence, repetitive transitions, forced groups
+  of three and multiple labels that say the same thing;
+- fake candor, invented objections, rejected options no reader proposed,
+  dramatic fragments and generic optimistic endings;
+- abstract metaphors, buzzwords or modifiers standing in for a concrete fact;
+- formatting used as decoration, including excessive bold text, emoji and a
+  list where one sentence is clearer;
+- comments or documentation that restate visible code instead of explaining a
+  non-obvious reason, constraint, risk or consequence.
+
+These are contextual signals, not a forbidden-word list. Keep a transition,
+technical term, passive construction, long sentence, repeated phrase or unusual
+punctuation when it is accurate, natural for the writer and useful to the
+reader. Professional grammar is not an AI tell.
+
+Never simulate humanity with typos, missing punctuation, fabricated anecdotes,
+random slang, artificial sentence fragments or opinions the author did not
+express. Do not optimize for an AI detector or claim that prose is human-written.
+
+## Match the artifact
+
+- **Reply, comment or status:** outcome first, then only decisive evidence,
+  blocker and next action.
+- **Email or request:** purpose, essential context, one clear ask and timing when
+  material.
+- **README or instructions:** purpose, prerequisites, shortest successful path,
+  verification and only likely failure recovery.
+- **Pull request:** lead with why the change is needed, then describe only the net
+  change against the actual PR base and the verification that helps review it.
+  Remove abandoned approaches, local absolute paths and routine checks already
+  evident from required CI; preserve still-relevant links, images and caveats.
+- **Report or decision note:** answer, verified facts, inference or trade-off,
+  decision and next action. Keep fact and inference visibly distinct.
+- **Long-form content:** thesis, evidence and implications in a coherent arc.
+  Concision removes repetition; it does not flatten a real argument into notes.
+- **Code comment:** explain why, invariant, risk or surprising consequence.
+  Delete comments that merely translate the code into English.
+- **Marketing or social copy:** audience problem, concrete value or proof and one
+  honest action. Do not manufacture urgency, authority or transformation.
+
+For a natural human feel, preserve the author's actual nouns, stance, uncertainty
+and occasional first-person phrasing when supplied. Prefer a specific example
+over a polished generalization. Do not manufacture typos, slang, anecdotes,
+opinions, emotional claims or "human" irregularity; do not optimize for an AI
+detector or claim that a person wrote the result.
+
+## Quality gate
+
+Before returning the text, require:
+
+```text
+PURPOSE_CLEAR: PASS | FAIL
+ANSWER_OR_ACTION_FRONT_LOADED: PASS | NOT_APPLICABLE | FAIL
+MEANING_PRESERVED: PASS | NOT_APPLICABLE | FAIL
+CLAIMS_TRACEABLE: PASS | NOT_APPLICABLE | FAIL
+CAVEATS_AND_CONDITIONS_PRESERVED: PASS | NOT_APPLICABLE | FAIL
+VOICE_AND_AUDIENCE_FIT: PASS | FAIL
+VALUE_DENSITY: PASS | FAIL
+SCAN_AND_ACCESSIBILITY: PASS | NOT_APPLICABLE | FAIL
+```
+
+`VALUE_DENSITY` passes when every sentence adds a distinct fact, implication,
+instruction, decision, transition or intentional voice effect. Ask of each
+sentence: if it disappears, does meaning, evidence, tone or action materially
+change? If not, cut it.
+
+A lower word count is diagnostic, not acceptance. Do not over-compress a short
+source, remove a necessary example, collapse separate conditions or hide risk.
+When accessibility matters, preserve descriptive headings, meaningful link text,
+expanded acronyms and enough context to understand the text out of layout.
+
+## Return the result
+
+Return only the finished prose by default. Do not surround a two-line answer
+with a process report. When the owner asks for an audit, comparison or measured
+compression of the prose itself, add a compact block after the result:
+
+```text
+MODE:
+WORDS: before -> after | NOT_MEASURED
+MATERIAL_CHANGES:
+PRESERVED_CONTRACT:
+UNVERIFIED_OR_INPUT_REQUIRED:
+```
+
+Return `INPUT_REQUIRED` instead of drafting when a missing fact, source, voice
+sample or constraint would force invention or materially change the result.

package/skills/nobrainer-writing/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "NoBrainer Writing"
+  short_description: "Write concise, natural comments, issues, stories, and prose."
+  default_prompt: "Use $nobrainer-writing; use nb-brief for a short, concrete comment, issue, bug report, or user story."