An evidence-first operating layer for turning repeated AI agent runs into reusable, auditable, and promotable workflow assets.
Architecture • Directory Map • Sensitive Data • Workflow KB • Skill Optimization • PaaS Service • Verified Recipe • MVP Report • Tools • Memory • Agent Rules
Runwiser is the product direction.
awesome-skill-workflows is the open repository that proves and packages that
direction.
This project is not a Xiaohongshu tool.
It is an evidence-first workflow operating layer for turning repeated agent work into verified, reusable, self-improving, and eventually serviceable workflow assets.
Most teams already have prompts, scripts, tools, and agent runs.
What they usually do not have is a reliable system that answers:
- which workflow actually worked,
- what proof was preserved,
- which gates passed or failed,
- what became reusable,
- what should evolve before the next run,
- and what can be exposed safely as a service surface.
Runwiser treats the workflow, its evidence, and its upgrade path as the durable asset.
Agent teams often collect many isolated skills, prompts, scripts, and tool tricks. That is useful, but it is not enough. A skill only becomes valuable when it can be selected, composed, run, reviewed, verified, and reused.
This repository treats workflows as the durable asset:
- skills are capability units,
- workflows are composed execution paths,
- scenarios are validation wrappers,
- run evidence is the proof layer,
- the workflow knowledge base is the reusable memory,
- self-evolution turns failures, review notes, and verification gaps into better future assets.
A run is not reusable because it looked good once.
Reusable assets only emerge after explicit evidence, review, verification, and promotion boundaries line up.
- run evidence stays in
runs/ - durable knowledge stays in
workflow-kb/ - promoted assets stay in
verified-recipes/ - failed but useful lessons stay in failed namespaces
This project does not treat self-evolution as free-form prompt drift.
Self-evolution is evidence-driven writeback:
- failures can become reusable guardrails,
- human review can trigger workflow upgrades,
- verification mismatches can force a correction path,
- long-lived rule changes are drafted before they are promoted.
See docs/self-evolution.md and evolution-drafts/.
This repository is not only a documentation surface.
It already defines a thin HTTP service boundary that exposes repo-owned workflow validation and readiness checks while preserving evidence semantics.
The key distinction is deliberate:
- technical validation can remain
partial - readiness can still be
accepted_for_paas
Those states are not collapsed into a vague "passed" badge.
See docs/paas-ready-workflow-service.md.
This repository is a framework for:
- workflow evidence and proof preservation
- bounded self-evolution from run evidence
- reusable workflow memory and promotion
- scenario-portable workflow validation
- service-ready workflow execution boundaries
The long-term goal is to turn repeatable workflows into reusable, measurable, improvable, and serviceable workflow assets.
Every useful run should make the next run better:
- clarify the task and constraints
- select the best matching skill assets
- compose and run the workflow
- score the result
- pass human review for high-risk steps
- verify whether the output actually met the target
- capture failure cases and reusable evidence
- write back the right lesson at the right layer
- promote only what passed the required gates
The reusable asset is the path, not just the final output.
The repository currently proves three distinct things:
- Workflow proof stack
- evidence, gates, verification, and promotion remain separate
- Bounded self-evolution
- runs can improve future assets without silently rewriting core rules
- PaaS-ready workflow service
- repo-owned workflow validation can be exposed over HTTP with explicit readiness semantics
The current deepest end-to-end scenario is still Xiaohongshu draft validation, but that scenario is a proof wrapper, not the product identity.
Runwiser is easiest to understand as a proof stack, not as a single success badge.
Each layer answers a different question:
| Layer | Question | Primary home |
|---|---|---|
| Run evidence | What actually happened in a concrete execution? | runs/ |
| Generic contracts | What is reusable across scenarios? | schemas/, workflows/, docs/action-verification.md |
| Bounded evolution | What should change before the next run? | evolution/, evolution-drafts/, docs/self-evolution.md |
| Durable knowledge | What can future runs retrieve and reuse? | workflow-kb/, skills/wiki/ |
| Scenario wrapper | Which local constraints proved or blocked the run? | scenarios/ |
| Service boundary | What can safely become an HTTP workflow surface? | services/workflow-api/, docs/paas-ready-workflow-service.md |
This separation is the core trust model:
- a quality score is not human approval,
- an action fact is not compliance proof,
- failed evidence can become a reusable guardrail without becoming a verified recipe,
- service readiness can be accepted without relabeling partial technical validation.
The current PaaS-readiness path is the clearest example of bounded self-evolution.
The system has positive draft-save proof from prior run evidence, including a
compliant draft boundary and clicked_publish=false. A later fresh
visible-session recheck hit a login-reset blocker. Instead of hiding that
blocker behind a vague "passed" label, the repository split the result:
- keep the orchestration's technical validation as
partial, - preserve the final technical terminal state as
blocked, - record the blocker as evidence,
- allow human-reviewed PaaS progression because the service boundary is thin, repo-owned, and constrained to readiness checks,
- keep the exact evidence references available for future validation runs.
That is what "self-evolution" means here: the workflow gets a better future boundary from evidence, but the technical record is not rewritten.
See:
docs/self-evolution.mddocs/paas-ready-workflow-service.mdruns/022-xhs-pi-paas-readiness-acceptance/
The PaaS readiness status uses two tracks:
| Track | Current status | Meaning |
|---|---|---|
| Technical validation | technical_validation.status=partial |
The latest orchestration did not fully pass because the fresh visible-session recheck is still blocked. |
| Product readiness | readiness_level=accepted_for_paas |
The workflow can progress as a service surface because the blocker is isolated, prior draft proof is positive, publish stayed disabled, and human-reviewed readiness accepted the bounded service scope. |
The accepted readiness verdict does not mean:
- the technical validation passed,
- live publish proof exists,
- the login-reset blocker disappeared,
- scenario-specific account rules moved into the generic architecture.
It means the repository can expose an evidence-backed readiness service without collapsing technical truth, human acceptance, and product progression into one ambiguous state.
The repository now uses a five-layer model:
- Layer 0: Raw / evidence
- concrete runs, proof, score, gates, and failed evidence
- Layer 1: Core skill architecture
- skill discovery and normalization
- workflow composition
- schemas, validators, and generic action-verification contracts
- Layer 2: Skill evolution / optimization
- SkillOpt-style bounded edits
- train / selection / test evidence split
- accepted and rejected candidate records
- Layer 3: Durable knowledge surface
- skill wiki
- workflow KB
- registry and retrieval index
- Layer 4: Scenario validation
- concrete scenario wrappers
- scenario-specific risk gates
- human-reviewed action handoff
A scenario can prove the architecture, but it must not define the architecture.
Version v0.1 uses Xiaohongshu AI tool content publishing as the validation scenario.
This scenario exists only to validate the platform design:
- the core skill architecture can absorb a real workflow
- the workflow can be reviewed by a human before high-risk actions
- success and failure can be captured into the knowledge base
- the system can reuse prior work in a second scenario
The validation scenario is intentionally concrete, but the architecture is meant to transfer to other repeatable agent workflows such as market research, competitor analysis, report generation, data monitoring, and operational review loops.
The MVP is considered complete only when the following loop works end to end:
- define a workflow scenario
- capture raw discovery
- structure it into skills, workflows, and recipes
- run or simulate the workflow
- record results, failures, and reusable patterns
- feed the outcome back into the workflow knowledge base
- use the updated knowledge base in the next run
See docs/directory-architecture.md for the placement rules and cleanup policy.
Core framework:
skills/: reusable skill assets, wiki pages, raw discovery, indexes, and capability mapsworkflows/: workflow definitions and orchestration patternsworkflow-kb/: durable reusable knowledge, retrieval entries, patterns, rubrics, fallback strategies, and failure casesschemas/: JSON schemas for skills, workflows, scenarios, scoring, gates, recipes, and verification recordsscripts/: project validators and promotion gate checksdocs/: architecture, principles, scoring, self-evolution, and directory rulesTOOLS.md: durable tool, command, environment, path, and platform usage notesMEMORY.md: durable project-local preferences and facts
Scenario and evidence:
scenarios/: scenario-specific validation wrappers, constraints, risk rules, and scoring rubricsruns/: records from specific workflow runs; evidence, not reusable truth by itselfevolution/: evidence-backed improvement notes and self-evolution outputsevolution-drafts/: pending, approved, and rejected proposals for long-lived rule updatesverified-recipes/: recipes promoted only after verification, human review, and reuse evidencefailed-recipes/: failed recipes that still produced reusable evidencereports/: generated summaries and review outputs
Use these files to understand the current validated state:
| Question | Primary evidence |
|---|---|
| What is the system architecture? | docs/architecture.md |
| How are high-risk action facts separated from compliance proof? | docs/action-verification.md |
| What principles constrain the project? | docs/principles.md |
| How should SkillOpt-style optimization fit? | docs/skillopt-integration.md |
| Can this claim official SkillOpt paper reproduction? | reports/skillopt-official-readiness.json |
| What is the current scenario? | scenarios/xiaohongshu-creator/scenario.md |
| What workflow was validated? | workflows/xiaohongshu/xhs-ai-tool-topic-to-post.workflow.md |
| What is the generic multi-agent workflow contract? | docs/multi-agent-workflows.md |
| What is the PaaS-ready workflow service contract? | docs/paas-ready-workflow-service.md |
| What is the current PaaS acceptance record? | runs/022-xhs-pi-paas-readiness-acceptance/ |
| How do SkillOpt artifacts promote into the skill wiki? | docs/skill-wiki-promotion.md |
| What skill wiki entry was promoted? | skills/wiki/xhs-kb-reuse-selection-gated-safety.md |
| What run passed draft validation? | runs/003-xhs-ai-agent-save-one-hour-step8-draft-rerun/ |
| What recipe is verified? | verified-recipes/xhs-ai-agent-save-one-hour.recipe.md |
| What failed evidence is preserved? | failed-recipes/xhs-ai-agent-save-one-hour.recipe.md |
| What reusable workflow is in the KB? | workflow-kb/verified-workflows/xhs-ai-tool-topic-to-post.v1.md |
| How does retrieval find reusable assets? | workflow-kb/retrieval-index.json |
| What is the MVP verdict? | reports/first-mvp-validation-report.md |
The current MVP scope is compliant draft validation, not live publishing.
The validated path proves that the workflow can:
- discover and normalize skills,
- compose a scenario workflow,
- generate and score content,
- pass human review and risk approval,
- confirm account state before handoff,
- save a compliant draft without clicking publish,
- write reusable success and failure evidence back into the knowledge base,
- reuse the knowledge base in a second scenario run.
See:
reports/first-mvp-validation-report.mdverified-recipes/xhs-ai-agent-save-one-hour.recipe.mdworkflow-kb/verified-workflows/xhs-ai-tool-topic-to-post.v1.md
The repository now also exposes a PaaS-ready multi-agent workflow service shell.
Current boundary:
- the generic Pi-backed multi-agent workflow contract is validated
- the Xiaohongshu real-run orchestration remains technically
partial - the Xiaohongshu workflow is still accepted for PaaS progression by
human-reviewed readiness logic because the real save-draft proof is positive,
clicked_publish=false, and the remaining blocker is isolated to a fresh visible-session login reset
See:
docs/paas-ready-workflow-service.mdservices/workflow-api/README.mdruns/018-xhs-pi-multi-agent-live-validation/runs/022-xhs-pi-paas-readiness-acceptance/
Start with:
AGENTS.mdfor agent operating rules.docs/architecture.mdfor the system model.docs/directory-architecture.mdfor placement rules.docs/sensitive-data-policy.mdbefore any account-bound run or promotion.docs/workflow-knowledge-base.mdfor KB writeback rules.docs/skill-wiki-promotion.mdfor promoting SkillOpt artifacts into the skill wiki.scenarios/<scenario>/for scenario-specific boundaries.workflow-kb/retrieval-index.jsonbefore starting any new run.
For a new workflow scenario:
- Define the scenario boundary in
scenarios/. - Capture raw skill discovery in
skills/raw-discovery/. - Normalize reusable capabilities into
skills/. - Compose the workflow in
workflows/. - Run or simulate the workflow and store evidence in
runs/. - Score the result and record human review or gate evidence.
- Write reusable outcomes into
workflow-kb/. - Promote only verified recipes into
verified-recipes/. - Store failed but useful evidence in
failed-recipes/orworkflow-kb/failure-cases/.
Before starting a new run, query workflow-kb/retrieval-index.json and the referenced KB files to avoid rediscovering known patterns.
Before promoting a workflow or recipe:
- Confirm the run has evidence under
runs/. - Confirm human review and risk gates when required.
- Confirm proof matches the approved mode.
- Keep failed evidence under failed namespaces.
- Update the retrieval index only with reusable assets.
- Run the promotion validator.
- Run the sensitive-boundary validator.
npm run paas:workflow-apiValidate the readiness path with:
npm run validate:xhs-paas-readiness
npm run validate:workflow-apiDo not promote a workflow or recipe because it looks useful. Promotion requires evidence.
- Failed recipes do not belong in
verified-recipes/. - Failed workflows do not belong in
workflow-kb/verified-workflows/. - A quality score is not the same as human review, risk approval, account-state proof, or draft/publish proof.
- Verified assets need explicit evidence references.
- Incomplete or blocked runs should remain as run evidence plus an evolution note or failure case.
- Live publish verification is separate from draft verification.
- Layer 1 uses the generic
action verificationcontract; scenario terms such asdraft_verifiedstay local and must map into, not replace, the Layer 1 model.
For the current Xiaohongshu scenario, draft_verified means human review, risk approval, account-state check, compliant draft proof, and clicked_publish=false all passed.
High-risk actions require human review. This repository should not be used for fully autonomous account actions.
Do not commit:
- local browser profiles,
- cookies or session files,
.envfiles,- credentials or private keys,
- scratch plans or local agent progress notes.
The .gitignore excludes known local-sensitive paths such as .gstack/, .xhs-creator-profile/, cookie JSON files, and local team planning files.
Before promoting reusable evidence, run:
node scripts/validate-sensitive-boundaries.mjsRun the validators after changing schemas, workflows, recipes, KB entries, reports, or promotion evidence:
node scripts/validate-mvp-acceptance.mjs
node scripts/validate-sensitive-boundaries.mjs
node scripts/validate-evolution-drafts.mjs
node scripts/validate-promotion-gates.mjsExpected current result:
- MVP acceptance:
PASS - Sensitive boundaries:
passed - Evolution drafts:
passed - Promotion gates:
passed
- The repository intentionally stores both successful and failed evidence.
- Failed evidence is useful, but it must not be stored in verified paths.
- Screenshots and browser proof are run evidence, not source-of-truth architecture.
- High-risk account-bound actions require human review.
- Refactors should be atomic: change one coherent asset boundary, validate it, then commit.
Agent behavior is defined in AGENTS.md.
Key operating expectations:
- keep Layer 1 scenario-agnostic,
- keep scenario-specific assumptions local to the scenario,
- make refactors and submissions atomic,
- validate before promotion,
- preserve sensitive local files outside git.
Licensed under the Apache License, Version 2.0. See LICENSE.