codeassembly-guidance 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +291 -0
- package/CHANGELOG.md +82 -0
- package/README.md +20 -121
- package/content/_partials/README.md +19 -3
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/guidance-change-since-capture.md +9 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +1 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/cli-conventions.md +16 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
- package/content/guidance/rulebooks/commit-conventions.md +3 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +31 -4
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +69 -69
- package/content/scripts/manage-jira-ticket.mjs +73 -73
- package/content/scripts/select-lede-exemplars.mjs +53 -53
- package/content/scripts/validate-preferences.mjs +1 -1
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +24 -3
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +12 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/title-templates.md +3 -1
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/cluster-feedback-events.md +21 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/next-steps-after-plan.md +1 -1
- package/content/skills/_partials/option-format.md +2 -2
- package/content/skills/_partials/plan-template.md +4 -2
- package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
- package/content/skills/assess-code-health/SKILL.md +127 -0
- package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
- package/content/skills/assess-usability/SKILL.md +3 -1
- package/content/skills/capture-event/SKILL.md +2 -0
- package/content/skills/capture-event/capture-event.mjs +32 -32
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/collaborate/SKILL.md +2 -2
- package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +4 -1
- package/content/skills/create-pr/SKILL.md +2 -1
- package/content/skills/create-ticket/SKILL.md +3 -7
- package/content/skills/curate-feedback/SKILL.md +102 -0
- package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
- package/content/skills/design-and-plan/SKILL.md +5 -9
- package/content/skills/implement-plan/SKILL.md +2 -2
- package/content/skills/index-prototypes/SKILL.md +1 -1
- package/content/skills/kb-add/SKILL.md +2 -0
- package/content/skills/kb-add/kb-add.mjs +53 -53
- package/content/skills/kb-curate/kb-curate.mjs +64 -64
- package/content/skills/kb-edit/SKILL.md +2 -0
- package/content/skills/kb-edit/kb-edit.mjs +59 -59
- package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
- package/content/skills/kb-retrieve-events/SKILL.md +19 -10
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
- package/content/skills/kb-update-events/SKILL.md +9 -6
- package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/review-branch/SKILL.md +350 -1
- package/content/skills/revise-prose/revise-prose.mjs +103 -103
- package/content/skills/save-artifact/SKILL.md +1 -1
- package/content/skills/streamline-guidance/SKILL.md +10 -15
- package/content/skills/streamline-guidance/streamline-guidance.mjs +74 -74
- package/content/skills/summarize-change/SKILL.md +1 -1
- package/content/skills/testing-conventions/SKILL.md +7 -1
- package/content/skills/triage-feedback/SKILL.md +135 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +6 -6
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
- package/content/skills/update-project-guidance/SKILL.md +10 -10
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/feedback-coverage-judge.md +95 -0
- package/content/subagents/feedback-triage-challenger.md +86 -0
- package/content/subagents/lesson-clusterer.md +68 -0
- package/package.json +13 -13
- package/schemas/preferences.v1.json +22 -6
- package/schemas/work-types.v1.json +1 -1
- package/content/_partials/code-descriptions.md +0 -4
- package/content/_partials/code-style.md +0 -7
- package/content/_partials/live-repo-writes.md +0 -13
- package/content/_partials/reduced-object-relative.md +0 -28
- package/content/_partials/test-structure-audit-checklist.md +0 -7
- package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
- package/content/skills/_partials/next-steps-after-review.md +0 -350
- package/content/skills/_partials/ticket-concision.md +0 -18
- package/content/skills/_partials/ticket-placement.md +0 -14
- package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
|
@@ -137,7 +137,7 @@ ${t.comment}`:t.comment}this.doc.range[2]=t.offset;break}default:this.errors.pus
|
|
|
137
137
|
`,t)+1}yield*this.pop();break;default:yield*this.pop(),yield*this.step()}}*blockMap(e){let t=e.items[e.items.length-1];switch(this.type){case"newline":if(this.onKeyLine=!1,t.value){let i="end"in t.value?t.value.end:void 0;(Array.isArray(i)?i[i.length-1]:void 0)?.type==="comment"?i?.push(this.sourceToken):e.items.push({start:[this.sourceToken]})}else t.sep?t.sep.push(this.sourceToken):t.start.push(this.sourceToken);return;case"space":case"comment":if(t.value)e.items.push({start:[this.sourceToken]});else if(t.sep)t.sep.push(this.sourceToken);else{if(this.atIndentedComment(t.start,e.indent)){let n=e.items[e.items.length-2]?.value?.end;if(Array.isArray(n)){Ht(n,t.start),n.push(this.sourceToken),e.items.pop();return}}t.start.push(this.sourceToken)}return}if(this.indent>=e.indent){let i=!this.onKeyLine&&this.indent===e.indent,n=i&&(t.sep||t.explicitKey)&&this.type!=="seq-item-ind",r=[];if(n&&t.sep&&!t.value){let o=[];for(let l=0;l<t.sep.length;++l){let c=t.sep[l];switch(c.type){case"newline":o.push(l);break;case"space":break;case"comment":c.indent>e.indent&&(o.length=0);break;default:o.length=0}}o.length>=2&&(r=t.sep.splice(o[1]))}switch(this.type){case"anchor":case"tag":n||t.value?(r.push(this.sourceToken),e.items.push({start:r}),this.onKeyLine=!0):t.sep?t.sep.push(this.sourceToken):t.start.push(this.sourceToken);return;case"explicit-key-ind":!t.sep&&!t.explicitKey?(t.start.push(this.sourceToken),t.explicitKey=!0):n||t.value?(r.push(this.sourceToken),e.items.push({start:r,explicitKey:!0})):this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:[this.sourceToken],explicitKey:!0}]}),this.onKeyLine=!0;return;case"map-value-ind":if(t.explicitKey)if(t.sep)if(t.value)e.items.push({start:[],key:null,sep:[this.sourceToken]});else if(Z(t.sep,"map-value-ind"))this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:r,key:null,sep:[this.sourceToken]}]});else if(bo(t.key)&&!Z(t.sep,"newline")){let o=we(t.start),l=t.key,c=t.sep;c.push(this.sourceToken),delete t.key,delete t.sep,this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:o,key:l,sep:c}]})}else r.length>0?t.sep=t.sep.concat(r,this.sourceToken):t.sep.push(this.sourceToken);else if(Z(t.start,"newline"))Object.assign(t,{key:null,sep:[this.sourceToken]});else{let o=we(t.start);this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:o,key:null,sep:[this.sourceToken]}]})}else t.sep?t.value||n?e.items.push({start:r,key:null,sep:[this.sourceToken]}):Z(t.sep,"map-value-ind")?this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:[],key:null,sep:[this.sourceToken]}]}):t.sep.push(this.sourceToken):Object.assign(t,{key:null,sep:[this.sourceToken]});this.onKeyLine=!0;return;case"alias":case"scalar":case"single-quoted-scalar":case"double-quoted-scalar":{let o=this.flowScalar(this.type);n||t.value?(e.items.push({start:r,key:o,sep:[]}),this.onKeyLine=!0):t.sep?this.stack.push(o):(Object.assign(t,{key:o,sep:[]}),this.onKeyLine=!0);return}default:{let o=this.startBlockValue(e);if(o){if(o.type==="block-seq"){if(!t.explicitKey&&t.sep&&!Z(t.sep,"newline")){yield*this.pop({type:"error",offset:this.offset,message:"Unexpected block-seq-ind on same line with key",source:this.source});return}}else i&&e.items.push({start:r});this.stack.push(o);return}}}}yield*this.pop(),yield*this.step()}*blockSequence(e){let t=e.items[e.items.length-1];switch(this.type){case"newline":if(t.value){let i="end"in t.value?t.value.end:void 0;(Array.isArray(i)?i[i.length-1]:void 0)?.type==="comment"?i?.push(this.sourceToken):e.items.push({start:[this.sourceToken]})}else t.start.push(this.sourceToken);return;case"space":case"comment":if(t.value)e.items.push({start:[this.sourceToken]});else{if(this.atIndentedComment(t.start,e.indent)){let n=e.items[e.items.length-2]?.value?.end;if(Array.isArray(n)){Ht(n,t.start),n.push(this.sourceToken),e.items.pop();return}}t.start.push(this.sourceToken)}return;case"anchor":case"tag":if(t.value||this.indent<=e.indent)break;t.start.push(this.sourceToken);return;case"seq-item-ind":if(this.indent!==e.indent)break;t.value||Z(t.start,"seq-item-ind")?e.items.push({start:[this.sourceToken]}):t.start.push(this.sourceToken);return}if(this.indent>e.indent){let i=this.startBlockValue(e);if(i){this.stack.push(i);return}}yield*this.pop(),yield*this.step()}*flowCollection(e){let t=e.items[e.items.length-1];if(this.type==="flow-error-end"){let i;do yield*this.pop(),i=this.peek(1);while(i?.type==="flow-collection")}else if(e.end.length===0){switch(this.type){case"comma":case"explicit-key-ind":!t||t.sep?e.items.push({start:[this.sourceToken]}):t.start.push(this.sourceToken);return;case"map-value-ind":!t||t.value?e.items.push({start:[],key:null,sep:[this.sourceToken]}):t.sep?t.sep.push(this.sourceToken):Object.assign(t,{key:null,sep:[this.sourceToken]});return;case"space":case"comment":case"newline":case"anchor":case"tag":!t||t.value?e.items.push({start:[this.sourceToken]}):t.sep?t.sep.push(this.sourceToken):t.start.push(this.sourceToken);return;case"alias":case"scalar":case"single-quoted-scalar":case"double-quoted-scalar":{let n=this.flowScalar(this.type);!t||t.value?e.items.push({start:[],key:n,sep:[]}):t.sep?this.stack.push(n):Object.assign(t,{key:n,sep:[]});return}case"flow-map-end":case"flow-seq-end":e.end.push(this.sourceToken);return}let i=this.startBlockValue(e);i?this.stack.push(i):(yield*this.pop(),yield*this.step())}else{let i=this.peek(2);if(i.type==="block-map"&&(this.type==="map-value-ind"&&i.indent===e.indent||this.type==="newline"&&!i.items[i.items.length-1].sep))yield*this.pop(),yield*this.step();else if(this.type==="map-value-ind"&&i.type!=="flow-collection"){let n=Qt(i),r=we(n);yo(e);let o=e.end.splice(1,e.end.length);o.push(this.sourceToken);let l={type:"block-map",offset:e.offset,indent:e.indent,items:[{start:r,key:e,sep:o}]};this.onKeyLine=!0,this.stack[this.stack.length-1]=l}else yield*this.lineEnd(e)}}flowScalar(e){if(this.onNewLine){let t=this.source.indexOf(`
|
|
138
138
|
`)+1;for(;t!==0;)this.onNewLine(this.offset+t),t=this.source.indexOf(`
|
|
139
139
|
`,t)+1}return{type:e,offset:this.offset,indent:this.indent,source:this.source}}startBlockValue(e){switch(this.type){case"alias":case"scalar":case"single-quoted-scalar":case"double-quoted-scalar":return this.flowScalar(this.type);case"block-scalar-header":return{type:"block-scalar",offset:this.offset,indent:this.indent,props:[this.sourceToken],source:""};case"flow-map-start":case"flow-seq-start":return{type:"flow-collection",offset:this.offset,indent:this.indent,start:this.sourceToken,items:[],end:[]};case"seq-item-ind":return{type:"block-seq",offset:this.offset,indent:this.indent,items:[{start:[this.sourceToken]}]};case"explicit-key-ind":{this.onKeyLine=!0;let t=Qt(e),i=we(t);return i.push(this.sourceToken),{type:"block-map",offset:this.offset,indent:this.indent,items:[{start:i,explicitKey:!0}]}}case"map-value-ind":{this.onKeyLine=!0;let t=Qt(e),i=we(t);return{type:"block-map",offset:this.offset,indent:this.indent,items:[{start:i,key:null,sep:[this.sourceToken]}]}}}return null}atIndentedComment(e,t){return this.type!=="comment"||this.indent<=t?!1:e.every(i=>i.type==="newline"||i.type==="space")}*documentEnd(e){this.type!=="doc-mode"&&(e.end?e.end.push(this.sourceToken):e.end=[this.sourceToken],this.type==="newline"&&(yield*this.pop()))}*lineEnd(e){switch(this.type){case"comma":case"doc-start":case"doc-end":case"flow-seq-end":case"flow-map-end":case"map-value-ind":yield*this.pop(),yield*this.step();break;case"newline":this.onKeyLine=!1;default:e.end?e.end.push(this.sourceToken):e.end=[this.sourceToken],this.type==="newline"&&(yield*this.pop())}}};wo.Parser=Ii});var Ao=y(Xe=>{"use strict";var So=bi(),Zf=Ue(),He=Ve(),eu=gs(),tu=O(),su=Ci(),vo=Pi();function ko(s){let e=s.prettyErrors!==!1;return{lineCounter:s.lineCounter||e&&new su.LineCounter||null,prettyErrors:e}}a(ko,"parseOptions");function iu(s,e={}){let{lineCounter:t,prettyErrors:i}=ko(e),n=new vo.Parser(t?.addNewLine),r=new So.Composer(e),o=Array.from(r.compose(n.parse(s)));if(i&&t)for(let l of o)l.errors.forEach(He.prettifyError(s,t)),l.warnings.forEach(He.prettifyError(s,t));return o.length>0?o:Object.assign([],{empty:!0},r.streamInfo())}a(iu,"parseAllDocuments");function No(s,e={}){let{lineCounter:t,prettyErrors:i}=ko(e),n=new vo.Parser(t?.addNewLine),r=new So.Composer(e),o=null;for(let l of r.compose(n.parse(s),!0,s.length))if(!o)o=l;else if(o.options.logLevel!=="silent"){o.errors.push(new He.YAMLParseError(l.range.slice(0,2),"MULTIPLE_DOCS","Source contains multiple documents; please use YAML.parseAllDocuments()"));break}return i&&t&&(o.errors.forEach(He.prettifyError(s,t)),o.warnings.forEach(He.prettifyError(s,t))),o}a(No,"parseDocument");function nu(s,e,t){let i;typeof e=="function"?i=e:t===void 0&&e&&typeof e=="object"&&(t=e);let n=No(s,t);if(!n)return null;if(n.warnings.forEach(r=>eu.warn(n.options.logLevel,r)),n.errors.length>0){if(n.options.logLevel!=="silent")throw n.errors[0];n.errors=[]}return n.toJS(Object.assign({reviver:i},t))}a(nu,"parse");function ru(s,e,t){let i=null;if(typeof e=="function"||Array.isArray(e)?i=e:t===void 0&&e&&(t=e),typeof t=="string"&&(t=t.length),typeof t=="number"){let n=Math.round(t);t=n<1?void 0:n>8?{indent:8}:{indent:n}}if(s===void 0){let{keepUndefined:n}=t??e??{};if(!n)return}return tu.isDocument(s)&&!i?s.toString(t):new Zf.Document(s,i,t).toString(t)}a(ru,"stringify");Xe.parse=nu;Xe.parseAllDocuments=iu;Xe.parseDocument=No;Xe.stringify=ru});var Oo=y(E=>{"use strict";var ou=bi(),au=Ue(),lu=zs(),$i=Ve(),cu=Oe(),ee=O(),fu=Q(),uu=T(),hu=X(),du=z(),pu=Wt(),mu=Li(),gu=Ci(),yu=Pi(),Xt=Ao(),qo=ke();E.Composer=ou.Composer;E.Document=au.Document;E.Schema=lu.Schema;E.YAMLError=$i.YAMLError;E.YAMLParseError=$i.YAMLParseError;E.YAMLWarning=$i.YAMLWarning;E.Alias=cu.Alias;E.isAlias=ee.isAlias;E.isCollection=ee.isCollection;E.isDocument=ee.isDocument;E.isMap=ee.isMap;E.isNode=ee.isNode;E.isPair=ee.isPair;E.isScalar=ee.isScalar;E.isSeq=ee.isSeq;E.Pair=fu.Pair;E.Scalar=uu.Scalar;E.YAMLMap=hu.YAMLMap;E.YAMLSeq=du.YAMLSeq;E.CST=pu;E.Lexer=mu.Lexer;E.LineCounter=gu.LineCounter;E.Parser=yu.Parser;E.parse=Xt.parse;E.parseAllDocuments=Xt.parseAllDocuments;E.parseDocument=Xt.parseDocument;E.stringify=Xt.stringify;E.visit=qo.visit;E.visitAsync=qo.visitAsync});import{readFile as Ou}from"node:fs/promises";import ze from"node:path";import K from"node:process";import{parseArgs as Eu}from"node:util";function _i(s){return s instanceof Error||Object.prototype.toString.call(s)==="[object Error]"}a(_i,"isError");function te(s){try{return _i(s)&&typeof s.message=="string"&&s.message!==""?s.message:String(s)}catch{return"[unstringifiable value]"}}a(te,"describeError");var _o=Yo(Oo(),1);import{realpathSync as Eo}from"node:fs";import Lo from"node:process";import{fileURLToPath as bu}from"node:url";function To(s,e){let t=Lo.argv[1];if(t===void 0)return!1;try{return Eo(bu(s))===Eo(t)}catch(i){return Lo.stderr.write(`${e}: warning: could not determine entry point: ${te(i)}
|
|
140
|
-
`),!0}}a(To,"isEntryPoint");function wu(s,e){return Io(s)&&s.code===e}a(wu,"isErrorCode");function Co(s){return wu(s,"ENOENT")}a(Co,"isEnoent");function Se(s){return Io(s)&&!Array.isArray(s)}a(Se,"isRecord");function Io(s){return typeof s=="object"&&s!==null}a(Io,"isObject");var Po={$schema:"https://json-schema.org/draft/2020-12/schema",title:"Preferences",description:"Configuration read by agent skills. Resolved from .agents/preferences.yaml at the project level, with ~/.agents/preferences.yaml as a global fallback.",type:"object",properties:{$schema:{type:"string",description:"JSON Schema reference URI for editor tooling."},artifacts:{type:"object",description:"Artifact storage configuration: where generated artifacts live and how they are categorized.",properties:{base_dir:{type:"string",description:"Root directory for all generated artifacts. Supports `~` expansion. Default: `~/ai-artifacts`."},paths:{type:"object",description:"Maps artifact category names (e.g., `chats`, `devlogs`, `plans`) to subdirectory names relative to the project artifact directory. Any category key is permitted; values must be strings.",additionalProperties:{type:"string"}}}},commit:{type:"object",description:"Commit-title rendering configuration consumed by the `describe-change.mjs` script.",properties:{title_format:{type:"string",description:"Template string used to render commit titles. Supports the tokens `{scope}`, `{type}`, `{breaking}`, `{title}`, and `{ticket_ref}`, and nesting `[...]` groups that drop when a token directly inside them resolves empty."}},required:["title_format"]},editors:{type:"array",description:"Optional list of editor configurations mapping file extensions to an editor command.",items:{type:"object",properties:{name:{type:"string",description:"Display name of the editor."},command:{type:"string",description:"Shell command to open files. The file path is appended as an argument."},extensions:{type:"string",description:"Glob pattern for file types this editor handles (e.g., `*.md`)."}},required:["name","command","extensions"]}},integrations:{type:"object",description:"Per-integration configuration. Keys are integration names (e.g., `jira`, `github`, `linear`); each integration object must declare an `enabled` boolean.",properties:{jira:{type:"object",description:"Jira integration configuration. Beyond `enabled`, the keys here are read by the `manage-jira-ticket` helper, which the `create-ticket` skill runs to create a Jira work item.",properties:{enabled:{type:"boolean",description:"Whether the integration is enabled."},issue_types:{type:"object",description:"Maps work-type keys and aliases (from the work-type taxonomy, e.g. `feat`, `fix`, `bugfix`) to Jira issue-type names, plus a `default` entry covering every unmapped work type. A created work item whose work type matches neither falls back to `Task`.",additionalProperties:{type:"string"}},project_key:{type:"string",description:"Key of the Jira project to create work items in (e.g., `MAC`). Overrides the key derived from `project.ticket_ref_prefix` minus its trailing separator."}},required:["enabled"]}},additionalProperties:{type:"object",properties:{enabled:{type:"boolean",description:"Whether the integration is enabled."}},required:["enabled"]}},merge:{type:"object",description:"Squash-merge title rendering configuration for the `merge-pr` skill family.",properties:{title_format:{type:"string",description:"Template string used to render the squash-merge commit title. Supports the same token vocabulary as `commit.title_format`, plus `{pr_number}`."},strategy:{type:"string",description:"Reserved key. Not yet honored by the `merge-pr` skill family \u2014 the skill currently performs squash merges unconditionally. Recorded here so the schema does not flag the key as unknown when projects opt to set it in anticipation of future support."},delete_branch:{type:"boolean",description:"Reserved key. Not yet honored by the `merge-pr` skill family \u2014 branch deletion is currently controlled by command-line flags and platform defaults. Recorded here so the schema does not flag the key as unknown when projects opt to set it in anticipation of future support."}}},platform:{type:"string",description:"Deprecated legacy spelling of `scm`, retained so existing preferences files validate during the migration window. Prefer `scm`; a future release removes this alias.",enum:["github","bitbucket"]},pr:{type:"object",description:"Pull-request title rendering configuration.",properties:{title_format:{type:"string",description:"Template string used to render pull-request titles. Supports the same token vocabulary as `commit.title_format`."}},required:["title_format"]},project:{type:"object",description:"Project identification configuration, and the project's declared stage (`maturity`, `sensitivity`, `audience`), which design guidance treats as premises.",properties:{audience:{type:"string",enum:["owner","team","public"],description:"Who uses the project. `owner`: only the repo's owner. `team`: a known, bounded group. `public`: anyone who can reach it. Read from the project preferences file only."},maturity:{type:"string",enum:["hobby","early","production"],description:"How far the project has come. `hobby`: built for the owner's own use or learning; breakage costs only the owner's time. `early`: in use by others, but the shape is still changing; downtime is tolerated. `production`: others depend on it; downtime and data loss have real costs. Read from the project preferences file only."},scopes:{type:"array",description:"Directories that own a change scope although they are not workspace packages, such as an app built by another toolchain. `describe-change resolve-scopes` resolves paths against these together with the pnpm workspace's packages, the longest containing directory winning. Read from the project preferences file only; the global file contributes no scopes. A declared directory does not become a workspace to any tool.",items:{type:"object",properties:{name:{type:"string",minLength:1,description:"Scope name. Defaults to the directory's basename, and overrides the basename of a package directory with the same path."},path:{type:"string",minLength:1,description:"Directory relative to the repository root. An absolute path, a path outside the repository, and a path that is not an existing directory are skipped with a warning."}},required:["path"],additionalProperties:!1}},sensitivity:{type:"string",enum:["low","personal","confidential"],description:"The most sensitive data that the project holds. `low`: nothing that would harm anyone if published. `personal`: personal data about the owner or identifiable individuals. `confidential`: secrets, credentials, or data that a third party is obliged to protect. Read from the project preferences file only."},slug:{type:"string",description:"Project identifier used for namespacing artifacts under `{base_dir}/projects/{slug}/`."},ticket_ref_prefix:{type:"string",description:"Prefix that appears at the start of `ticket_ref`. Use `#` for GitHub issues (added at render time, omitted from file paths) or a Jira project key like `MAC-` (part of the canonical ticket ID)."}}},repository:{type:"object",description:"Repository configuration: default remote and (deprecated) project slug fallback.",properties:{default_remote:{type:"object",description:"Default git remote used when constructing remote refs such as `origin/main`.",properties:{name:{type:"string",description:"Name of the default git remote (e.g., `origin`)."},default_branch:{type:"string",description:"Default branch of the remote (e.g., `main`)."}},required:["name","default_branch"]},slug:{type:"string",description:"Deprecated. Use `project.slug` instead. Kept as a fallback."}}},scm:{type:"string",description:"Source-code-management host. Supported values are `github` and `bitbucket`; new hosts can be added additively.",enum:["github","bitbucket"]},ticket:{type:"object",description:"Ticket (issue) configuration: title rendering, the base URL used to resolve bare ticket references, and the `pull-from-backlog` settings.",properties:{title_format:{type:"string",description:"Template string used to render ticket (issue) titles. Supports the same token vocabulary as `commit.title_format`."},base_url:{type:"string",description:"Org-stable base URL that a bare ticket id is appended to when reconstructing a ticket URL, for platforms where the URL cannot otherwise be derived (e.g. Jira `https://org.atlassian.net/browse/`). The trailing slash is optional. Surfaced into the branch manifest as `ticket_base_url`."},pull:{type:"object",description:"Settings of the `pull-from-backlog` skill, read from the project preferences file only.",properties:{assignOnPick:{type:"boolean",default:!1,description:"Assign the user to a picked ticket without asking first."},excludeLabels:{type:"array",items:{type:"string",minLength:1},default:["status:blocked","status:on-hold"],description:"Labels that make a ticket ineligible to be pulled, matched without regard to case. An ineligible ticket is never a candidate and does not count toward picking the Now milestone. An empty list disables exclusion."},now:{type:"string",minLength:1,description:"Title of the open milestone that forms the Now set. Without it, the Now set is the open milestone with the nearest due date, else the open milestone with the most open eligible issues (see `excludeLabels`), else the whole backlog."},priorityPrefix:{type:"string",minLength:1,default:"priority:",description:"Prefix of the priority labels. The value after it ranks `high`, `medium`, then `low`; any other value ranks as unlabelled."},staleBranchDays:{type:"integer",minimum:1,default:14,description:"Days since an in-progress branch's last commit at which the skill warns about it."},staleGroomDays:{type:"integer",minimum:1,default:14,description:"Days since the last groom at which the skill offers `/groom-backlog`."},staleGroomNewTickets:{type:"integer",minimum:1,default:10,description:"Open tickets created since the last groom at which the skill offers `/groom-backlog`."}},additionalProperties:!1}},required:["title_format"]}},additionalProperties:!1};function $o(s,e){let t=Math.max(1,Math.floor(s.length/3)),i;for(let n of e.toSorted()){let r=vu(s.toLowerCase(),n.toLowerCase());r<=t&&(i===void 0||r<i.distance)&&(i={key:n,distance:r})}return i?.key}a($o,"findNearestKey");function vu(s,e){let t=Array.from({length:e.length+1},(i,n)=>n);for(let i=1;i<=s.length;i++){let n=[i];for(let r=1;r<=e.length;r++){let o=(t[r-1]??0)+(s[i-1]===e[r-1]?0:1);n[r]=Math.min((t[r]??0)+1,(n[r-1]??0)+1,o)}t=n}return t[e.length]??0}a(vu,"measureEditDistance");function Mo(s,e){let t=[];return zt(s,e,[],t),t}a(Mo,"validatePreferences");function ku(s){return s.length===0?"(root)":s.map((e,t)=>typeof e=="number"?`[${e}]`:t===0?e:`.${e}`).join("")}a(ku,"formatPath");function Nu(s,e){switch(e){case"array":return Array.isArray(s);case"boolean":return typeof s=="boolean";case"integer":return Number.isSafeInteger(s);case"number":return typeof s=="number";case"object":return Se(s);case"string":return typeof s=="string";default:return!0}}a(Nu,"matchesType");function ve(s,e,t,i){s.push({level:e,path:ku(t),message:i})}a(ve,"report");function Au(s,e,t,i){if(e.items!==void 0)for(let[n,r]of s.entries())zt(r,e.items,[...t,n],i)}a(Au,"walkArray");function qu(s,e,t,i){let n=Se(e.properties)?e.properties:void 0,r=e.required;if(Array.isArray(r))for(let o of r)typeof o=="string"&&!Object.hasOwn(s,o)&&ve(i,"error",t,`missing required key '${o}'`);for(let[o,l]of Object.entries(s)){let c=[...t,o];if(n!==void 0&&Object.hasOwn(n,o))zt(l,n[o],c,i);else if(Se(e.additionalProperties))zt(l,e.additionalProperties,c,i);else if(n!==void 0&&e.additionalProperties!==!0){let f=$o(o,Object.keys(n)),p=f===void 0?"":`; did you mean '${f}'?`;ve(i,"warning",c,`unrecognized key${p}`)}}}a(qu,"walkObject");function zt(s,e,t,i){if(Se(e)){if(e.type!==void 0&&!Nu(s,e.type)){let n=typeof e.type=="string"?e.type:JSON.stringify(e.type);ve(i,"error",t,`expected ${n} (got ${JSON.stringify(s)})`);return}if(Array.isArray(e.enum)&&!e.enum.includes(s)){let n=e.enum.map(r=>JSON.stringify(r)).join(", ");ve(i,"error",t,`must be one of ${n} (got ${JSON.stringify(s)})`)}typeof e.minLength=="number"&&typeof s=="string"&&s.length<e.minLength&&ve(i,"error",t,`must be at least ${e.minLength} characters long`),typeof e.minimum=="number"&&typeof s=="number"&&s<e.minimum&&ve(i,"error",t,`must be at least ${e.minimum} (got ${s})`),Se(s)?qu(s,e,t,i):Array.isArray(s)&&Au(s,e,t,i)}}a(zt,"walkValue");async function Lu(s,e,t=Do(K.argv[1])){if(s.includes("--help")||s.includes("-h"))return K.stdout.write(Tu(t)),0;let i;try{i=Iu(s)}catch(l){return K.stderr.write(`${t}: ${te(l)}; run ${t} --help for usage
|
|
140
|
+
`),!0}}a(To,"isEntryPoint");function wu(s,e){return Io(s)&&s.code===e}a(wu,"isErrorCode");function Co(s){return wu(s,"ENOENT")}a(Co,"isEnoent");function Se(s){return Io(s)&&!Array.isArray(s)}a(Se,"isRecord");function Io(s){return typeof s=="object"&&s!==null}a(Io,"isObject");var Po={$schema:"https://json-schema.org/draft/2020-12/schema",title:"Preferences",description:"Configuration read by agent skills. Resolved from .agents/preferences.yaml at the project level, with ~/.agents/preferences.yaml as a global fallback.",type:"object",properties:{$schema:{type:"string",description:"JSON Schema reference URI for editor tooling."},artifacts:{type:"object",description:"Artifact storage configuration: where generated artifacts live and how they are categorized.",properties:{base_dir:{type:"string",description:"Root directory for all generated artifacts. Supports `~` expansion. Default: `~/ai-artifacts`."},paths:{type:"object",description:"Maps artifact category names (e.g., `chats`, `devlogs`, `plans`) to subdirectory names relative to the project artifact directory. Any category key is permitted; values must be strings.",additionalProperties:{type:"string"}}}},commit:{type:"object",description:"Commit-title rendering configuration consumed by the `describe-change.mjs` script.",properties:{title_format:{type:"string",description:"Template string used to render commit titles. Supports the tokens `{scope}`, `{type}`, `{breaking}`, `{title}`, and `{ticket_ref}`, and nesting `[...]` groups that drop when a token directly inside them resolves empty."}},required:["title_format"]},editors:{type:"array",description:"Optional list of editor configurations mapping file extensions to an editor command.",items:{type:"object",properties:{name:{type:"string",description:"Display name of the editor."},command:{type:"string",description:"Shell command to open files. The file path is appended as an argument."},extensions:{type:"string",description:"Glob pattern for file types this editor handles (e.g., `*.md`)."}},required:["name","command","extensions"]}},integrations:{type:"object",description:"Per-integration configuration. Keys are integration names (e.g., `jira`, `github`, `linear`); each integration object must declare an `enabled` boolean.",properties:{jira:{type:"object",description:"Jira integration configuration. Beyond `enabled`, the keys here are read by the `manage-jira-ticket` helper, which the `create-ticket` skill runs to create a Jira work item.",properties:{enabled:{type:"boolean",description:"Whether the integration is enabled."},issue_types:{type:"object",description:"Maps work-type keys and aliases (from the work-type taxonomy, e.g. `feat`, `fix`, `bugfix`) to Jira issue-type names, plus a `default` entry covering every unmapped work type. A created work item whose work type matches neither falls back to `Task`.",additionalProperties:{type:"string"}},project_key:{type:"string",description:"Key of the Jira project to create work items in (e.g., `MAC`). Overrides the key derived from `project.ticket_ref_prefix` minus its trailing separator."}},required:["enabled"]}},additionalProperties:{type:"object",properties:{enabled:{type:"boolean",description:"Whether the integration is enabled."}},required:["enabled"]}},merge:{type:"object",description:"Squash-merge title rendering configuration for the `merge-pr` skill family.",properties:{title_format:{type:"string",description:"Template string used to render the squash-merge commit title. Supports the same token vocabulary as `commit.title_format`, plus `{pr_number}`."},strategy:{type:"string",description:"Reserved key. Not yet honored by the `merge-pr` skill family \u2014 the skill currently performs squash merges unconditionally. Recorded here so the schema does not flag the key as unknown when projects opt to set it in anticipation of future support."},delete_branch:{type:"boolean",description:"Reserved key. Not yet honored by the `merge-pr` skill family \u2014 branch deletion is currently controlled by command-line flags and platform defaults. Recorded here so the schema does not flag the key as unknown when projects opt to set it in anticipation of future support."}}},platform:{type:"string",description:"Deprecated legacy spelling of `scm`, retained so existing preferences files validate during the migration window. Prefer `scm`; a future release removes this alias.",enum:["github","bitbucket"]},pr:{type:"object",description:"Pull-request configuration: title rendering and the state at creation.",properties:{initial_state:{type:"string",enum:["draft","ready"],description:"The state in which `create-pr` opens a pull request: `draft`, or `ready` for review. Defaults to `draft`."},title_format:{type:"string",description:"Template string used to render pull-request titles. Supports the same token vocabulary as `commit.title_format`."}}},project:{type:"object",description:"Project identification configuration, and the project's declared stage (`maturity`, `sensitivity`, `audience`), which design guidance treats as premises.",properties:{audience:{type:"string",enum:["owner","team","public"],description:"Who uses the project. `owner`: only the repo's owner. `team`: a known, bounded group. `public`: anyone who can reach it. Read from the project preferences file only."},maturity:{type:"string",enum:["hobby","early","production"],description:"How far the project has come. `hobby`: built for the owner's own use or learning; breakage costs only the owner's time. `early`: in use by others, but the shape is still changing; downtime is tolerated. `production`: others depend on it; downtime and data loss have real costs. Read from the project preferences file only."},scopes:{type:"array",description:"Directories that own a change scope although they are not workspace packages, such as an app built by another toolchain. `describe-change resolve-scopes` resolves paths against these together with the pnpm workspace's packages, the longest containing directory winning. Read from the project preferences file only; the global file contributes no scopes. A declared directory does not become a workspace to any tool.",items:{type:"object",properties:{name:{type:"string",minLength:1,description:"Scope name. Defaults to the directory's basename, and overrides the basename of a package directory with the same path."},path:{type:"string",minLength:1,description:"Directory relative to the repository root. An absolute path, a path outside the repository, and a path that is not an existing directory are skipped with a warning."}},required:["path"],additionalProperties:!1}},sensitivity:{type:"string",enum:["low","personal","confidential"],description:"The most sensitive data that the project holds. `low`: nothing that would harm anyone if published. `personal`: personal data about the owner or identifiable individuals. `confidential`: secrets, credentials, or data that a third party is obliged to protect. Read from the project preferences file only."},slug:{type:"string",description:"Project identifier used for namespacing artifacts under `{base_dir}/projects/{slug}/`."},ticket_ref_prefix:{type:"string",description:"Prefix that appears at the start of `ticket_ref`. Use `#` for GitHub issues (added at render time, omitted from file paths) or a Jira project key like `MAC-` (part of the canonical ticket ID)."}}},repository:{type:"object",description:"Repository configuration: default remote and (deprecated) project slug fallback.",properties:{default_remote:{type:"object",description:"Default git remote used when constructing remote refs such as `origin/main`.",properties:{name:{type:"string",description:"Name of the default git remote (e.g., `origin`)."},default_branch:{type:"string",description:"Default branch of the remote (e.g., `main`)."}},required:["name","default_branch"]},slug:{type:"string",description:"Deprecated. Use `project.slug` instead. Kept as a fallback."}}},scm:{type:"string",description:"Source-code-management host. Supported values are `github` and `bitbucket`; new hosts can be added additively.",enum:["github","bitbucket"]},ticket:{type:"object",description:"Ticket (issue) configuration: title rendering, the base URL used to resolve bare ticket references, and the `pull-from-backlog` settings.",properties:{title_format:{type:"string",description:"Template string used to render ticket (issue) titles. Supports the same token vocabulary as `commit.title_format`."},base_url:{type:"string",description:"Org-stable base URL that a bare ticket id is appended to when reconstructing a ticket URL, for platforms where the URL cannot otherwise be derived (e.g. Jira `https://org.atlassian.net/browse/`). The trailing slash is optional. Surfaced into the branch manifest as `ticket_base_url`."},pull:{type:"object",description:"Settings of the `pull-from-backlog` skill, read from the project preferences file only.",properties:{assignOnPick:{type:"boolean",default:!1,description:"Assign the user to a picked ticket without asking first."},excludeLabels:{type:"array",items:{type:"string",minLength:1},default:["status:blocked","status:on-hold"],description:"Labels that make a ticket ineligible to be pulled, matched without regard to case. An ineligible ticket is never a candidate and does not count toward picking the Now milestone. An empty list disables exclusion."},now:{type:"string",minLength:1,description:"Title of the open milestone that forms the Now set. Without it, the Now set is the open milestone with the nearest due date, else the open milestone with the most open eligible issues (see `excludeLabels`), else the whole backlog."},priorityPrefix:{type:"string",minLength:1,default:"priority:",description:"Prefix of the priority labels. The value after it ranks `high`, `medium`, then `low`; any other value ranks as unlabelled."},staleBranchDays:{type:"integer",minimum:1,default:14,description:"Days since an in-progress branch's last commit at which the skill warns about it."},staleGroomDays:{type:"integer",minimum:1,default:14,description:"Days since the last groom at which the skill offers `/groom-backlog`."},staleGroomNewTickets:{type:"integer",minimum:1,default:10,description:"Open tickets created since the last groom at which the skill offers `/groom-backlog`."}},additionalProperties:!1}},required:["title_format"]},triage_feedback:{type:"object",description:"Settings of the `triage-feedback` skill.",properties:{defer_days:{type:"integer",minimum:1,description:"The days for which a deferred feedback cluster stays out of a triage, unless it gains an undeferred event. Defaults to 30."}}}},additionalProperties:!1};function $o(s,e){let t=Math.max(1,Math.floor(s.length/3)),i;for(let n of e.toSorted()){let r=vu(s.toLowerCase(),n.toLowerCase());r<=t&&(i===void 0||r<i.distance)&&(i={key:n,distance:r})}return i?.key}a($o,"findNearestKey");function vu(s,e){let t=Array.from({length:e.length+1},(i,n)=>n);for(let i=1;i<=s.length;i++){let n=[i];for(let r=1;r<=e.length;r++){let o=(t[r-1]??0)+(s[i-1]===e[r-1]?0:1);n[r]=Math.min((t[r]??0)+1,(n[r-1]??0)+1,o)}t=n}return t[e.length]??0}a(vu,"measureEditDistance");function Mo(s,e){let t=[];return zt(s,e,[],t),t}a(Mo,"validatePreferences");function ku(s){return s.length===0?"(root)":s.map((e,t)=>typeof e=="number"?`[${e}]`:t===0?e:`.${e}`).join("")}a(ku,"formatPath");function Nu(s,e){switch(e){case"array":return Array.isArray(s);case"boolean":return typeof s=="boolean";case"integer":return Number.isSafeInteger(s);case"number":return typeof s=="number";case"object":return Se(s);case"string":return typeof s=="string";default:return!0}}a(Nu,"matchesType");function ve(s,e,t,i){s.push({level:e,path:ku(t),message:i})}a(ve,"report");function Au(s,e,t,i){if(e.items!==void 0)for(let[n,r]of s.entries())zt(r,e.items,[...t,n],i)}a(Au,"walkArray");function qu(s,e,t,i){let n=Se(e.properties)?e.properties:void 0,r=e.required;if(Array.isArray(r))for(let o of r)typeof o=="string"&&!Object.hasOwn(s,o)&&ve(i,"error",t,`missing required key '${o}'`);for(let[o,l]of Object.entries(s)){let c=[...t,o];if(n!==void 0&&Object.hasOwn(n,o))zt(l,n[o],c,i);else if(Se(e.additionalProperties))zt(l,e.additionalProperties,c,i);else if(n!==void 0&&e.additionalProperties!==!0){let f=$o(o,Object.keys(n)),p=f===void 0?"":`; did you mean '${f}'?`;ve(i,"warning",c,`unrecognized key${p}`)}}}a(qu,"walkObject");function zt(s,e,t,i){if(Se(e)){if(e.type!==void 0&&!Nu(s,e.type)){let n=typeof e.type=="string"?e.type:JSON.stringify(e.type);ve(i,"error",t,`expected ${n} (got ${JSON.stringify(s)})`);return}if(Array.isArray(e.enum)&&!e.enum.includes(s)){let n=e.enum.map(r=>JSON.stringify(r)).join(", ");ve(i,"error",t,`must be one of ${n} (got ${JSON.stringify(s)})`)}typeof e.minLength=="number"&&typeof s=="string"&&s.length<e.minLength&&ve(i,"error",t,`must be at least ${e.minLength} characters long`),typeof e.minimum=="number"&&typeof s=="number"&&s<e.minimum&&ve(i,"error",t,`must be at least ${e.minimum} (got ${s})`),Se(s)?qu(s,e,t,i):Array.isArray(s)&&Au(s,e,t,i)}}a(zt,"walkValue");async function Lu(s,e,t=Do(K.argv[1])){if(s.includes("--help")||s.includes("-h"))return K.stdout.write(Tu(t)),0;let i;try{i=Iu(s)}catch(l){return K.stderr.write(`${t}: ${te(l)}; run ${t} --help for usage
|
|
141
141
|
`),1}let n=i.files.length===0,r=n?[ze.join(".agents","preferences.yaml")]:i.files,o=[];for(let l of r)o.push(await Pu(ze.resolve(e,l),{isOptional:n,isStrict:i.strict}));if(i.json)for(let l of o)K.stdout.write(`${JSON.stringify(l)}
|
|
142
142
|
`);else K.stdout.write(Cu(o,e,t));return o.every(l=>l.valid)?0:1}a(Lu,"runValidatePreferences");if(To(import.meta.url,"validate-preferences")){let s=Do(K.argv[1]);try{K.exit(await Lu(K.argv.slice(2),K.cwd(),s))}catch(e){K.stderr.write(`${s}: ${te(e)}
|
|
143
143
|
`),K.exit(1)}}function Tu(s){return[`${s}: validate preferences.yaml files against the preferences schema bundled with this release`,"",`Usage: ${s} [--json] [--strict] [file...]`,"","Arguments:"," file A preferences file to validate. Every named file must exist."," Without one, validates .agents/preferences.yaml, which may be absent.","","Options:"," --json Print one JSON object per file: { file, present, valid, findings }"," --strict Treat warnings, such as an unrecognized key, as failures"," -h, --help Print this help","","Exits 1 when any file is invalid, and 0 otherwise.","","Example:",` ${s} --strict .agents/preferences.yaml ~/.agents/preferences.yaml`,""].join(`
|
|
@@ -27,6 +27,8 @@ Each is an action item. Restate it in the block as the concrete action that it p
|
|
|
27
27
|
|
|
28
28
|
The sweep runs in both directions. Having moved every ask into the block, read the block back and ask of each item whether it is really a question: An item whose answer follows from evidence that the agent already holds is a decision that it declined to make, and handing it back makes the user evaluate what a clause would have stated. Strike it, state the decision in the prose with its reason, and leave the block to the items that only the user can settle. An item that the agent could perform is a step that it declined to take: Run it, and leave in the block only the part that the agent cannot perform, named with its reason. A plan's "the owner exercises `/lab/book-row` by keyboard and on a touch device" is the counterexample: The agent drives the route through a debug browser, and the block holds at most how the control feels on a physical phone. A block emptied this way is a turn without an ask, which is a report rather than a failure.
|
|
29
29
|
|
|
30
|
+
An overload signal from the user, such as "I can't do this any more" or a count of the commands that they have run, empties the block in every turn until the user asks for something; the "Prompt formatting" section of the collaboration preferences states the rule.
|
|
31
|
+
|
|
30
32
|
## Items
|
|
31
33
|
|
|
32
34
|
An item is a question, punctuated as one, naming the concrete action:
|
|
@@ -8,6 +8,7 @@ The artifact directory is the developer's audit trail of development. Its plans,
|
|
|
8
8
|
|
|
9
9
|
- **Durable content.** Put instructions, a procedure, or a reference that a later session must find in the repository (its docs, `AGENTS.md`, or a README), or in a skill or rulebook when they apply across repositories. A later session looks there, not in the artifact directory.
|
|
10
10
|
- **Authority.** An artifact is not authority on the current state of code, design, or decisions. Treat what a search of artifacts turns up as history, and verify it against the repository, the tickets, and the pull requests.
|
|
11
|
+
- **Conclusions.** A conclusion that a reader of the ticket needs is posted on the ticket, and the artifact keeps the evidence. For a spike, see [Closing post](spike-conventions.md#closing-post).
|
|
11
12
|
- **Inputs to the same work.** A skill that reads an artifact as an input to the same piece of work, such as the plan that `implement-plan` executes or the change summary that `create-pr` publishes, uses the artifact as the workflow intends.
|
|
12
13
|
|
|
13
14
|
## Directory structure
|
|
@@ -28,6 +29,10 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
|
|
|
28
29
|
│ ├── usability/ ← a usability assessment's lens reports and evidence, kept by `assess-usability`
|
|
29
30
|
│ │ ├── {lens}-report.md
|
|
30
31
|
│ │ └── {lens}/{finding-id}-{slug}.png
|
|
32
|
+
│ ├── code-health/ ← a code-health assessment's sense document, reports, and proposals, kept by `assess-code-health`
|
|
33
|
+
│ │ ├── sense.json
|
|
34
|
+
│ │ ├── {lens}/report.md
|
|
35
|
+
│ │ └── {lens}/proposals.json
|
|
31
36
|
│ ├── triage/ ← a findings triage's working files, kept by `triage-spike-findings`
|
|
32
37
|
│ │ ├── findings.md
|
|
33
38
|
│ │ ├── inventory.md
|
|
@@ -49,6 +54,12 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
|
|
|
49
54
|
│ └── {timestamp}_{slug}_deferred-findings.md ← project-scoped fallback when a ticket is not in session
|
|
50
55
|
├── devlogs/
|
|
51
56
|
│ └── {timestamp}_{concise-title}.md ← project-scoped fallback when a ticket is not in session
|
|
57
|
+
├── feedback-curation/
|
|
58
|
+
│ ├── {timestamp}_{slug}_feedback-curation.md ← project-scoped fallback when a ticket is not in session
|
|
59
|
+
│ └── {timestamp}_work/ ← the run's working files
|
|
60
|
+
├── feedback-triage/
|
|
61
|
+
│ ├── {timestamp}_{slug}_feedback-triage.md ← project-scoped fallback when a ticket is not in session
|
|
62
|
+
│ └── {timestamp}_work/ ← the run's working files
|
|
52
63
|
└── plans/
|
|
53
64
|
└── {design-documents}.md
|
|
54
65
|
```
|
|
@@ -71,6 +82,10 @@ A `project.ticket_ref_prefix` other than `#` is part of the ticket ID, so it nam
|
|
|
71
82
|
|
|
72
83
|
`usability/` contains the working files of the ticket's usability assessment: each lens's report and each lens's evidence, which is screenshots in a browser assessment and transcripts in a CLI assessment. The `usability-findings` artifact cites the evidence by paths relative to the ticket directory, so the evidence stays in the ticket directory. A CLI assessment's fixtures are scratch directories outside the ticket directory, and nothing keeps them.
|
|
73
84
|
|
|
85
|
+
### Code-health working files
|
|
86
|
+
|
|
87
|
+
`code-health/` contains the working files of the ticket's code-health assessment: the sense document with each check's log beside it, the test reports that the sensors read, each lens's report and checked proposals, and the merged proposals. The `code-health-findings` artifact cites code by paths relative to the repository root, so it does not depend on these files; they record what the run measured.
|
|
88
|
+
|
|
74
89
|
### Triage working files
|
|
75
90
|
|
|
76
91
|
`triage/` contains the working files of a triage of the ticket's findings: a local copy of the findings when they came from an artifact URL, the inventory, the recommendations that the challenger reads, the challenger's reply, the dispositions record from which the `dispositions` artifact is rendered, and the comments rendered from that record: `preview/` with placeholders for the confirmation, `rendered/` with every number for posting. The record stays here as a working file; the artifact is the rendered text.
|
|
@@ -134,11 +149,13 @@ Ticket-level artifacts and run directories are both stored here. Invoke the bund
|
|
|
134
149
|
| chats | `chats` | `{base_dir}/projects/{project-slug}/chats/` |
|
|
135
150
|
| deferred-findings | `deferred-findings` | `{base_dir}/projects/{project-slug}/deferred-findings/` |
|
|
136
151
|
| devlogs | `devlogs` | `{base_dir}/projects/{project-slug}/devlogs/` |
|
|
152
|
+
| feedback-curation | `feedback-curation` | `{base_dir}/projects/{project-slug}/feedback-curation/` |
|
|
153
|
+
| feedback-triage | `feedback-triage` | `{base_dir}/projects/{project-slug}/feedback-triage/` |
|
|
137
154
|
| plans | `plans` | `{base_dir}/projects/{project-slug}/plans/` |
|
|
138
155
|
|
|
139
|
-
Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with
|
|
156
|
+
Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with three exceptions: `deferred-findings`, `feedback-curation`, and `feedback-triage` are hardcoded and cannot be overridden.
|
|
140
157
|
|
|
141
|
-
Devlogs
|
|
158
|
+
Devlogs, deferred-findings, feedback-curation, and feedback-triage artifacts are dual-homed: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket-id}/`; otherwise they fall back to the project-scoped paths above (`devlogs/`, `deferred-findings/`, `feedback-curation/`, and `feedback-triage/`). All filenames in these types use the standard `YYYYMMDD-HHMMSSZ` ticket-level timestamp shape regardless of which directory they are written to.
|
|
142
159
|
|
|
143
160
|
## Naming conventions
|
|
144
161
|
|
|
@@ -713,7 +730,7 @@ Full run state (phases, artifacts, review rounds, criticalities) is reconstructe
|
|
|
713
730
|
|
|
714
731
|
### Backward compatibility
|
|
715
732
|
|
|
716
|
-
|
|
733
|
+
The run-core parser, `parseRunData`, still reads the v2 `run-index.json` format and the v1 `status.json` format.
|
|
717
734
|
|
|
718
735
|
## Artifact types
|
|
719
736
|
|
|
@@ -734,10 +751,14 @@ The first `coder_change-summary` in a run does not have dispositions (nothing to
|
|
|
734
751
|
|
|
735
752
|
- `brief`: The shared brief that a round of prototype builders receives; `prepare-prototype-brief` saves it at its checkpoint
|
|
736
753
|
- `change-summary`: Branch change summary for PRs
|
|
754
|
+
- `code-health-brief`: The brief that every lens of a code-health assessment reads: the unit and its hotspots, the reuse-candidate directory and library inventory, the lenses with their rulebooks and caps, and the exclusions; `assess-code-health` saves it at its checkpoint
|
|
755
|
+
- `code-health-findings`: The merged, ungraded proposals of a code-health assessment, ranked by reach and hotspot rank, with the proposed groupings, the proposals that a prior triage or an issue already tracks, the residual unknowns, and the lens reports; `assess-code-health` saves it, and `triage-spike-findings` reads it
|
|
737
756
|
- `comparison`: Findings across a round of prototypes: the points on which they agree and those on which they diverge, a table of every distinctive idea with an empty decision, and which decisions the round leaves open; `prepare-prototype-brief` saves it after the index
|
|
738
757
|
- `deferred-findings`: Record of findings deferred during a `wrap-up` session, with cross-references to created tickets (falls back to non-ticket path when a ticket is not in session)
|
|
739
758
|
- `dispositions`: The rendered dispositions of a triage of findings, the text that `triage-spike-findings` posts on the triage ticket: every item with its disposition, its confidence and value, where it went, and its reason, with the challenge's summary; the JSON record from which it is rendered stays in `triage/`
|
|
740
759
|
- `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
|
|
760
|
+
- `feedback-curation`: The record of a `curate-feedback` run: the count of events in each bin, the guidance commits against which the judges read, each mark with its result, and every event with its bin, reference, and reason; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
|
|
761
|
+
- `feedback-triage`: The record of a `triage-feedback` run: each surfaced cluster of feedback events with its signals, priority, challenge, disposition, and result, and the remainder left in the pool. A deferred event's `addressed-by` names the artifact, whose filename timestamp dates the deferral; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
|
|
741
762
|
- `idea-decisions`: The idea table of a round of prototypes with the decision on each idea filled; `prepare-prototype-brief` saves it after the developer decides each idea, and the end vision cites it
|
|
742
763
|
- `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
|
|
743
764
|
- `plan`: Implementation plan document
|
|
@@ -49,7 +49,7 @@ Each consuming skill defines which complexity levels qualify for its "simple eno
|
|
|
49
49
|
| `design-and-plan` / `plan` handoff pass | 1–2 | Skip the handoff pass; the session reports the skip in one line that names the level, and saves the artifacts |
|
|
50
50
|
| `next-steps-after-plan` | 1–2 | Recommend "Implement". When a review pass would catch nothing meaningful (e.g., a typo or unused-import removal), note on the option that the review can be skipped at `implement-plan`'s closing menu. |
|
|
51
51
|
| `implement-plan` closing menu | 1–2 | Recommend "Create PR without review"; the realized diff is trivial enough that a review pass would catch nothing meaningful |
|
|
52
|
-
| `
|
|
52
|
+
| `review-branch` closing menu | n/a | Trivial findings usually name a single change, for which the skill recommends "Implement directly and commit"; the recommendation depends on the finding's shape rather than on the level. |
|
|
53
53
|
|
|
54
54
|
When characteristics span two levels, prefer the higher level.
|
|
55
55
|
|
|
@@ -63,14 +63,25 @@ The factual lists about each option are similar; the **ranking** flips because t
|
|
|
63
63
|
|
|
64
64
|
When designing a change, ask: _How would we have written this if the new behavior had been there from the start?_ Aim the design at that target.
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
Four patterns signal a design that hasn't reached it:
|
|
67
67
|
|
|
68
68
|
- **Workarounds**: Changing surrounding code to accommodate a fix instead of changing the code that's wrong.
|
|
69
69
|
- **Carve-outs**: Special cases or conditional branches that exist because the change couldn't be integrated cleanly, not because the cases are genuinely distinct.
|
|
70
70
|
- **Bolt-ons**: New modules or extension points appended alongside existing structure when the existing structure should have evolved to absorb the change.
|
|
71
|
+
- **Hand-offs**: Steps that a person performs on each machine or environment because the design did not give the agent a way to apply the change there. See [who applies the change](#who-applies-the-change).
|
|
71
72
|
|
|
72
73
|
A fresh codebase wouldn't have these shapes; their presence means the change was attached to the system rather than integrated into it. Reaching the target may require touching code outside the ticket's literal scope: renaming, restructuring, generalizing. That cost is real but bounded; the cost of keeping a poorly integrated change compounds.
|
|
73
74
|
|
|
75
|
+
## Who applies the change
|
|
76
|
+
|
|
77
|
+
The developer's manual steps are a cost of the design, counted across the session rather than per turn: Every command that a person runs on a machine, and every result that they paste back, is a step that the design failed to script. Rank a design that the agent applies and verifies itself above one that needs a person to act on each machine, whatever the convenience properties say. A step that a person must run on each machine is a defect of the design: Raise it at design time, and never ship it as README steps, written after the merge, for a person to follow.
|
|
78
|
+
|
|
79
|
+
When the design cannot remove the step, shape it on this ladder, and stop at the first rung that works:
|
|
80
|
+
|
|
81
|
+
1. Reach the machine through the access that its own tooling already uses, such as `ssh`, and apply the step there. When this rung needs a credential or a grant, ask for it once, naming the command that runs once it arrives.
|
|
82
|
+
2. Route the step through provisioning that the machine already runs, such as the ensure scripts of its configuration repository, so that the agent commits the change and the machine applies it on its next run.
|
|
83
|
+
3. Leave one script per machine, run once, that checks its own result and prints only the facts that the agent needs. The agent writes and commits the script and keeps every other part, including the records of what was done.
|
|
84
|
+
|
|
74
85
|
## Reconciliation
|
|
75
86
|
|
|
76
87
|
These rules reinforce "push back on questionable legacy": the guidance to examine, not preserve, carve-outs labelled "for backward compatibility" or "matches existing convention" when normalization would not break any concrete consumer.
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Spike conventions
|
|
2
2
|
|
|
3
|
-
Spike work is an investigation, not a build: Its artifacts answer questions and enable a decision rather than deliver observable software behavior. This file defines the spike-shaped ticket and plan templates that the ticket- and plan-authoring skills use in place of their feature templates when the work is a spike.
|
|
3
|
+
Spike work is an investigation, not a build: Its artifacts answer questions and enable a decision rather than deliver observable software behavior. This file defines the spike-shaped ticket and plan templates that the ticket- and plan-authoring skills use in place of their feature templates when the work is a spike, and the [closing post](#closing-post) that ends every spike.
|
|
4
|
+
|
|
5
|
+
The ticket is the record of a spike, and the findings artifact is its log: The artifact holds the full findings and the evidence, and the ticket holds what the spike concluded. See [Purpose](artifact-conventions.md#purpose) for the artifact directory's role.
|
|
4
6
|
|
|
5
7
|
Spike mode is entered explicitly (the invocation signals it) and is not auto-detected from ticket type, label, or title. Everything outside the two templates below (source resolution, staleness, Q&A, saving) is unchanged from the feature flow.
|
|
6
8
|
|
|
@@ -37,12 +39,12 @@ The concision and content-placement doctrines for feature tickets and plans appl
|
|
|
37
39
|
|
|
38
40
|
- [ ] {A decision that the findings must make possible.}
|
|
39
41
|
|
|
40
|
-
Deliverable: a findings & recommendation artifact.
|
|
42
|
+
Deliverable: a findings & recommendation artifact, and the closing post on this ticket.
|
|
41
43
|
```
|
|
42
44
|
|
|
43
45
|
`Context` and `Scope` are opt-in: Include either only when it adds signal on which the reader must act.
|
|
44
46
|
|
|
45
|
-
Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is a first-class section; acceptance criteria are questions-to-answer and decisions-to-enable rather than observable-behavior checkboxes; the spike ticket does not have a test or documentation criterion; the deliverable is a findings artifact, saved via the standard `save-artifact` conventions (without a dedicated artifact type).
|
|
47
|
+
Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is a first-class section; acceptance criteria are questions-to-answer and decisions-to-enable rather than observable-behavior checkboxes; the spike ticket does not have a test or documentation criterion; the deliverable is a findings artifact, saved via the standard `save-artifact` conventions (without a dedicated artifact type), and the [closing post](#closing-post) on the ticket.
|
|
46
48
|
|
|
47
49
|
## Spike plan template
|
|
48
50
|
|
|
@@ -59,7 +61,7 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
|
|
|
59
61
|
|
|
60
62
|
## Decisions taken
|
|
61
63
|
|
|
62
|
-
- {
|
|
64
|
+
- {🔲 while it awaits the checkpoint} {A decision that the agent took without asking, with its one-line reason.}
|
|
63
65
|
|
|
64
66
|
## Timebox
|
|
65
67
|
|
|
@@ -79,10 +81,23 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
|
|
|
79
81
|
|
|
80
82
|
## Deliverable
|
|
81
83
|
|
|
82
|
-
{The findings & recommendation artifact
|
|
84
|
+
{The findings & recommendation artifact (the answers reached, a recommendation, and residual unknowns), and the closing post on the ticket, offered at the closing checkpoint and made on consent, per `spike-conventions.md` § Closing post.}
|
|
83
85
|
```
|
|
84
86
|
|
|
85
|
-
Differences from the feature plan: Investigation steps, each framed by the question that it probes, replace tasks with create/modify/test file lists; `Timebox` is first-class; `Deliverable` replaces `Verification`, since a spike produces findings rather than verifiable behavior; a step does not have a test or documentation criterion.
|
|
87
|
+
Differences from the feature plan: Investigation steps, each framed by the question that it probes, replace tasks with create/modify/test file lists; `Timebox` is first-class; `Deliverable` replaces `Verification`, since a spike produces findings rather than verifiable behavior, and it names the [closing post](#closing-post); a step does not have a test or documentation criterion.
|
|
88
|
+
|
|
89
|
+
## Closing post
|
|
90
|
+
|
|
91
|
+
The agent that ends a spike posts its conclusion on the ticket as a comment. The post contains:
|
|
92
|
+
|
|
93
|
+
- The answer to each of the ticket's questions to answer.
|
|
94
|
+
- The recommendation on each of the ticket's decisions to enable.
|
|
95
|
+
- The counts and the proposed groupings, when the spike produced them.
|
|
96
|
+
- Links to the published page, when the spike published one, and to the findings artifact, with the artifact's path written `~/`-relative, so that the post does not publish a home-directory path.
|
|
97
|
+
|
|
98
|
+
Offer the post as an item in the closing action-items block, show its body, and post it only on consent: It is a remote write, and the developer is the one who can tell whether a finding is fit for the ticket's tracker. When the session does not have a ticket, do not offer it.
|
|
99
|
+
|
|
100
|
+
Pass the body through a file, per [gh body file](ticket-source-resolution.md#gh-body-file). Before posting, read the ticket's comments, and skip the post when a comment already opens with the post's first line, so that a rerun does not post it twice.
|
|
86
101
|
|
|
87
102
|
## Aligning a spike
|
|
88
103
|
|
|
@@ -199,13 +199,15 @@ node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entrie
|
|
|
199
199
|
```
|
|
200
200
|
|
|
201
201
|
```json
|
|
202
|
-
{ "consolidated_record": { "breaking": false, "scope": "agents", "type": "feat" } }
|
|
202
|
+
{ "consolidated_record": { "breaking": false, "scope": "agents", "type": "feat" }, "defects": [] }
|
|
203
203
|
```
|
|
204
204
|
|
|
205
205
|
**Each entry expands to one record per scope**, and an entry that does not name a scope expands to one record without a scope, so that a change that does not touch any scope can still be ranked by its type. The expanded list is then ranked exactly as `consolidate-branch` ranks the commit entries, so one rule serves both sources: breaking outranks non-breaking, then the tier and listing order in [`work-types.json`](./work-types.json), and exactly one distinct scope survives.
|
|
206
206
|
|
|
207
207
|
**An entry whose `type` the taxonomy does not declare is left as written and is unrankable**, so it does not contribute a type, as an unrankable commit entry does. Every field of `consolidated_record` is `null` for an empty list, which is how a caller distinguishes a change without entries from one whose consolidated record does not name a scope.
|
|
208
208
|
|
|
209
|
+
**`defects` lists the entry defects that [`resolve-merge`](#resolve-merge) reports for the same entries**: an `undeclared-type` or `policy-violation` whose `entry` names the entry's 0-based index, in entry order, or `[]` when every entry passes. The run reports them and continues.
|
|
210
|
+
|
|
209
211
|
**The run reads the entries from a file rather than from flags** because `text` is arbitrary prose containing backticks and quotes, which a shell argument would expand or truncate.
|
|
210
212
|
|
|
211
213
|
The run refuses an entries file that cannot be read, that is not valid YAML, or that is malformed, naming the defect: a value that is not a list, an item that is not a mapping, a missing or blank `type` or `text`, a `breaking` that is not a boolean, a `scopes` that is not a list of strings, and a `migration` that is not a string or spans more than one line, and a `text` or `migration` cut short by a YAML comment, which a space followed by `#` opens in an unquoted value; the error names the entry, the field, and the dropped text. A blank or null `migration` reads as absent, and a key that the grammar does not declare is ignored. It also refuses outright if the taxonomy cannot be read, since the entries have nothing to rank against.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
1. Apply each approved edit with {tool:Edit}, phrase to phrase. Stop at the first edit that does not match, and report which edit diverged.
|
|
2
|
+
2. Bump the `version` of each rulebook for which an edit changed what the rulebook asks: a rulebook that an edit changed, and a rulebook that includes an edited file. Find the second kind by searching the rulebooks for an include directive that names the edited file.
|
|
3
|
+
3. Run the project's quality gate as {skill:development-workflows} resolves it.
|
|
4
|
+
- If it fails only on a version pin or content hash that records a file edited by this run, apply the remedy that its failure message names: Update the pin to the version bumped above, or update the pin alone if the edits did not change what the rulebook asks.
|
|
5
|
+
- If it fails on anything else that an edit caused, restore that edit's text, report the edit, and run the gate again. If the restored edit was the only edit to change what its rulebook asks, also restore that rulebook's `version`, and its pin if this step updated it.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
An inventory is clustered in batches, because one clusterer cannot place every event of a large store. Each batch is clustered on its own, and when there is more than one, a merge pass groups the batch clusters that teach the same lesson.
|
|
2
|
+
|
|
3
|
+
1. Run `lesson-clusters inventory --store <store> --out {work}/inventory.json`. Report each `skipped` file, and stop when `pool` and `deferred` are both zero: Nothing awaits attention.
|
|
4
|
+
2. Run `lesson-clusters batch --inventory {work}/inventory.json --out {work}/batches`. Its `batches` list gives each batch's `path` and the `map` path to which its clusterer writes.
|
|
5
|
+
3. Send one {tool:Task} call per batch, all in one message, `subagent_type: lesson-clusterer`, each with this block and nothing else composed into it:
|
|
6
|
+
|
|
7
|
+
```dispatch
|
|
8
|
+
inventory: {batch path}
|
|
9
|
+
output: {batch map path}
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
4. When there is one batch, its map is the event map: Copy `{work}/batches/map-01.json` to `{work}/map.json`, and skip sub-steps 5 to 7.
|
|
13
|
+
5. Run `lesson-clusters lessons --batches {work}/batches --out {work}/lessons.json`. On `invalid-map`, resume the clusterer of each batch that the `violations` name once, sending it that batch's violations and asking it to correct its map; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. Run `lessons` again, and on a second failure, stop and report the violations.
|
|
14
|
+
6. Send one more {tool:Task} call, `subagent_type: lesson-clusterer`, for the merge pass:
|
|
15
|
+
|
|
16
|
+
```dispatch
|
|
17
|
+
inventory: {work}/lessons.json
|
|
18
|
+
output: {work}/merge.json
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
7. Run `lesson-clusters combine --batches {work}/batches --lessons {work}/lessons.json --map {work}/merge.json --out {work}/map.json`. On `invalid-map`, resume the merge clusterer once with the violations, run `combine` again, and on a second failure, stop and report them.
|
|
@@ -11,4 +11,4 @@ Pass `--ticket-ref` from the bundled session-context deriver so that a project w
|
|
|
11
11
|
|
|
12
12
|
Parse the output with a JSON parser (`python3` above; `jq -r '.commit_title'` if `jq` is available) rather than `grep` or `cut`: A rendered title may contain backslash-escaped double quotes, which a regex extractor silently truncates.
|
|
13
13
|
|
|
14
|
-
The pipeline prints the rendered title. Read it from the command's output and use it verbatim as the commit title, which already contains the rendered prefix, per the configured `commit.title_format`, and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the commit call, so copy the title as literal text into the message file. If the script is not found,
|
|
14
|
+
The pipeline prints the rendered title. Read it from the command's output and use it verbatim as the commit title, which already contains the rendered prefix, per the configured `commit.title_format`, and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the commit call, so copy the title as literal text into the message file. If the script is not found, or the pipeline prints an empty title because `commit.title_format` is empty or unset, use the bare `{title}`.
|
|
@@ -16,7 +16,7 @@ Present all three options as a numbered list per [option format](#option-format)
|
|
|
16
16
|
|
|
17
17
|
**One `➕` line is mandatory rather than omitted.** When Refine plan is the selected option, it must include a `➕` line naming the specific unsettled decision that the pass would raise (rule 1). The line names an open decision, never a reassurance about work already done: "a refine pass is the cheap way to find out whether I missed something" is the shape that this requirement exists to forbid. When Split the ticket is the selected option, it must include a `➕` line naming the plan's size and the pieces (rule 2). Selecting either without its line is a defect: If the line cannot be written, the rule did not match and the cascade continues.
|
|
18
18
|
|
|
19
|
-
**Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff, and `implement-plan` reads only the feature shape. Render option 3 as 🔬 Investigate, without invoking a skill; the agent works the investigation steps directly. Option 1 renders unchanged. Option 2 renders at □□□ with the `➖` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
|
|
19
|
+
**Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff, and `implement-plan` reads only the feature shape. Render option 3 as 🔬 Investigate, without invoking a skill; the agent works the investigation steps directly and ends the run with the plan's `## Deliverable`, which includes offering the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and making it on consent. Option 1 renders unchanged. Option 2 renders at □□□ with the `➖` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
|
|
20
20
|
|
|
21
21
|
Options that invoke a skill include context-clearing guidance:
|
|
22
22
|
|
|
@@ -14,11 +14,11 @@ The gated class is closed. Ask about these decisions whatever the markers say:
|
|
|
14
14
|
|
|
15
15
|
Decide everything else yourself by default. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; hold the gated action itself until the developer authorizes it. A templated next-steps menu is in the class, because what to do next is a preference about the developer's time, for which you do not hold any evidence. Verification is never in the gated class: Run a check that a command, a test, or a browser could settle.
|
|
16
16
|
|
|
17
|
-
**Proceed provisionally.** Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the skill's checkpoint. When a gated decision has a strong recommendation, build on it, mark it
|
|
17
|
+
**Proceed provisionally.** Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the skill's checkpoint. When a gated decision has a strong recommendation, build on it, mark it 🔲 as "Record what you did not ask" states, and ask at the checkpoint; revise if overruled. In a skill without a phase structure, treat the skill's own approval gate, or the end of its work, as the checkpoint.
|
|
18
18
|
|
|
19
19
|
**Batch, never stream.** Collect the asks that survive the gate into one review at the checkpoint, not one per turn.
|
|
20
20
|
|
|
21
|
-
**Record what you did not ask.** Write every decision that the gate let you take into the plan's `## Decisions taken` section, with a one-line reason; when the work does not have a plan, write it into the turn's summary. Always record: A silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with
|
|
21
|
+
**Record what you did not ask.** Write every decision that the gate let you take into the plan's `## Decisions taken` section, with a one-line reason; when the work does not have a plan, write it into the turn's summary. Always record: A silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with 🔲, wherever you state it: in the record, and in a turn's narrative, such as a checkpoint summary or a list of decisions. The marker lets the developer find what they may overrule without reading every line. Drop it once the developer approves the checkpoint at which the decision was presented.
|
|
22
22
|
|
|
23
23
|
**Never rank the options by your own elapsed time, round trips, or effort.** You measure these costs yourself, and that measure counts the user's context switch and review cycles as nothing. Measuring one does not make the call yours, and a more accurate measurement still cannot rank the options.
|
|
24
24
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
|
|
14
14
|
## Decisions taken
|
|
15
15
|
|
|
16
|
-
- {
|
|
16
|
+
- {🔲 while it awaits the checkpoint} {A decision that the agent took without asking, with its one-line reason}
|
|
17
17
|
|
|
18
18
|
## Tasks
|
|
19
19
|
|
|
@@ -56,13 +56,15 @@
|
|
|
56
56
|
|
|
57
57
|
**Per-task README guidance:** When a task writes or revises a README, consult {rulebook:readme-conventions} while planning the task. Its key decisions name the rulebook, the table row that fits the README, and what that row says the README leads with, keeps, and omits, so that the constraints are available to an implementer that cannot load the rulebook.
|
|
58
58
|
|
|
59
|
+
**Per-task documentation placement:** When a task writes or revises guidance or documentation, its key decisions name the source that defines each fact that the task documents, and the task writes a pointer to that source rather than a copy, per the "Documentation placement" section of the shared agent instructions.
|
|
60
|
+
|
|
59
61
|
**Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook's browser check of each new or changed interactive element.
|
|
60
62
|
|
|
61
63
|
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge.
|
|
62
64
|
|
|
63
65
|
**Per-task invoked-skill guidance:** When a task invokes a skill, read that skill while planning the task and record in the task's key decisions what the skill declares under three headings: its ordering relative to other skills, its default target when the task does not pass an argument, and the preconditions that it states. Read every skill that the plan's tasks name, and record a skill declaring none of the three as declaring none, so that a reader can tell a completed check from an absent one. A skill that cannot be read is recorded as unread, never as declaring none. When an ordering constraint names a skill that the plan's tasks do not invoke, add the task rather than record the constraint alone.
|
|
64
66
|
|
|
65
|
-
**Who performs a step.** Every task and every `## Verification` check names the agent as its actor. A part that only the developer can perform is written as a `**Residue:**` line under the task, after **What:** and in the same position as **Key decisions:**, in the form "**Residue:** {what the developer alone can do}: {why the agent cannot}", and the task's other parts stay the agent's. Check a resource's availability before naming it as a risk; when a step needs something that only the developer can supply, such as a credential or a running service, the step states the ask for that resource, never a degraded fallback and never the step as the developer's. A manual check is cut when an automated test or a check in `## Verification` asserts the same observable outcome, and stays, as the agent's, when it would show something that the tests do not assert. A check proposed against a deployed branch accounts for a `live` worktree, which runs the merged tree rather than the branch.
|
|
67
|
+
**Who performs a step.** Every task and every `## Verification` check names the agent as its actor. A part that only the developer can perform is written as a `**Residue:**` line under the task, after **What:** and in the same position as **Key decisions:**, in the form "**Residue:** {what the developer alone can do}: {why the agent cannot}", and the task's other parts stay the agent's. A residue that a person must perform on each machine is one script per machine, run once, which checks its own result and prints only the facts that the agent needs; the agent writes and commits the script. A record of the work, such as a log entry or a ticket comment, is never residue, and the residue is never shipped as documentation for a person to follow. Check a resource's availability before naming it as a risk; when a step needs something that only the developer can supply, such as a credential or a running service, the step states the ask for that resource, never a degraded fallback and never the step as the developer's. A manual check is cut when an automated test or a check in `## Verification` asserts the same observable outcome, and stays, as the agent's, when it would show something that the tests do not assert. A check proposed against a deployed branch accounts for a `live` worktree, which runs the merged tree rather than the branch.
|
|
66
68
|
|
|
67
69
|
Before (a verification task handed to the developer):
|
|
68
70
|
|
|
@@ -7,7 +7,7 @@ The handoff test has two halves, and each needs a different reader. The sweep ch
|
|
|
7
7
|
**Sweep for:**
|
|
8
8
|
|
|
9
9
|
- Settled decisions, including the rejected alternatives.
|
|
10
|
-
- Decisions that the agent took without asking: Every one is in the plan's `## Decisions taken` section, with its reason, marked
|
|
10
|
+
- Decisions that the agent took without asking: Every one is in the plan's `## Decisions taken` section, with its reason, marked 🔲 when it awaits this checkpoint.
|
|
11
11
|
- Constraints and scope boundaries on which the conversation agreed.
|
|
12
12
|
- Edge cases and success criteria raised in discussion but missing from the acceptance criteria.
|
|
13
13
|
- Tacit context of the form "the implementer might not realize X": What the conversation established as known and the artifacts leave the reader to rediscover.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
Start from this skeleton. Add a section only when it adds signal on which the reader must act.
|
|
2
|
+
|
|
3
|
+
- **Problem** and **Acceptance criteria (Must have)**: Always present.
|
|
4
|
+
- **Context**, **Proposed solution** (including "X, not Y"), and **Should have / Nice to have**: Opt-in, added only when the reader needs them. Omit empty tiers.
|
|
5
|
+
|
|
6
|
+
This applies the [concision principle](../_data/concision.md) to tickets.
|
|
7
|
+
|
|
8
|
+
**Write the tightened ticket, not a draft to be tightened later.** A ticket is the minimal contract that a reader needs, not a transcript of the design session. Compose the maximally tight version that still keeps the full meaning; length comes from content, not from a completeness instinct. (Producing the tight version up front spares the reader, and spares everyone the tighten-on-request round trip.)
|
|
9
|
+
|
|
10
|
+
State conclusions, not the journey to them. Naming a chosen approach (including "X, not Y") is a durable decision and belongs in the ticket. The _story_ of how the decision was reached does not: Drop the design back-and-forth, the false starts, restated context, and motivating episodes.
|
|
11
|
+
|
|
12
|
+
**Self-check before presenting.** For each sentence, ask: Would removing it change what the reader does or how the work gets executed? If not, cut it. State each acceptance criterion once, and do not restate it in surrounding prose.
|
|
13
|
+
|
|
14
|
+
Add a design-narrative section (rationale, alternatives explored) only when the user explicitly asks for it.
|
|
15
|
+
|
|
16
|
+
**Before** (the design journey is left in):
|
|
17
|
+
|
|
18
|
+
> We first considered extending the existing `FooAdapter`, but a spike showed it couples the cache to the transport, so after some back-and-forth we landed on a separate `CacheLayer`. The team has struggled with cache invalidation before, and this should finally fix that. Acceptance: A new `CacheLayer` module exists. It must be covered by tests so we know it works.
|
|
19
|
+
|
|
20
|
+
**After** (conclusion only, full meaning intact):
|
|
21
|
+
|
|
22
|
+
> Add a `CacheLayer` separate from the transport (not an extension of `FooAdapter`, which would couple cache to transport).
|
|
23
|
+
>
|
|
24
|
+
> - [ ] `CacheLayer` is independent of the transport.
|
|
25
|
+
> - [ ] New behavior is covered by tests.
|
|
26
|
+
|
|
27
|
+
**Place ticket content by kind, not by volume.** A ticket states the change's _subject_ and the _outcomes_ that it must produce; the _mechanism_ that achieves them belongs with the implementation, not the ticket. This is a separate axis from concision: A perfectly short ticket can still contain the wrong _kind_ of content.
|
|
28
|
+
|
|
29
|
+
- **Ticket**: The change's **subject** (the defect being fixed, the current structure being changed, the target contract or behavior that it exposes) and **key** non-obvious details that save the implementer real derivation (e.g. "reuse the sibling table's `getSortValue`").
|
|
30
|
+
- **Implementation**: The **mechanism**, meaning internal wiring, files as a diff-list, step sequences, deletion lists, and the internal props/config of a dependency consumed by the change.
|
|
31
|
+
|
|
32
|
+
The line is subject vs. mechanism, not code vs. prose: A code name is fine when it _is_ the subject. **Bug and refactoring tickets** name existing code because that code is the subject. Keep it; the fix procedure still belongs with the implementation.
|
|
33
|
+
|
|
34
|
+
**Before** (a feature ticket transcribing a reference implementation's API surface):
|
|
35
|
+
|
|
36
|
+
> Set `columnDefs`, pass `getSortedRowModel`, and wire `state.sorting`; pin the first column via `columnPinning.left: ['name']`; mock `@acme/table` in `__mocks__/@acme/table/compiled.tsx`.
|
|
37
|
+
|
|
38
|
+
**After** (the same change stated as the contract that it must honor):
|
|
39
|
+
|
|
40
|
+
> Every column sorts client-side, and the first column stays pinned during horizontal scroll. (Which props wire this up is implementation.)
|
|
@@ -10,4 +10,18 @@
|
|
|
10
10
|
|
|
11
11
|
{The shape of the proposed approach: components or boundaries involved, how it fits into the existing system, and the chosen approach, including "X, not Y" when a rejected option is worth recording. Keep this section outcome-shaped per the placement doctrine below.}
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## Acceptance criteria
|
|
14
|
+
|
|
15
|
+
Include only the tiers that have criteria. Omit any empty tier; do not emit a "Should have" or "Nice to have" header with nothing under it.
|
|
16
|
+
|
|
17
|
+
### Must have
|
|
18
|
+
|
|
19
|
+
- [ ] {Critical requirement}
|
|
20
|
+
|
|
21
|
+
### Should have
|
|
22
|
+
|
|
23
|
+
- [ ] {Important but not blocking}
|
|
24
|
+
|
|
25
|
+
### Nice to have
|
|
26
|
+
|
|
27
|
+
- [ ] {Optional enhancement}
|
|
@@ -37,13 +37,9 @@ The artifact begins with YAML frontmatter conforming to the [universal artifact
|
|
|
37
37
|
<!-- include: ../_partials/ticket-skeleton.md / -->
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
<!-- include: ../_partials/ticket-skeleton-tiers.md / -->
|
|
41
|
-
|
|
42
40
|
## Guidance
|
|
43
41
|
|
|
44
|
-
<!-- include: ../_partials/ticket-
|
|
45
|
-
|
|
46
|
-
<!-- include: ../_partials/ticket-placement.md / -->
|
|
42
|
+
<!-- include: ../_partials/ticket-composition.md / -->
|
|
47
43
|
|
|
48
44
|
When aligning to an existing implementation, _the implementation_ is the code on the branch; describe what the code now does, and resist transcribing its mechanism back into the ticket.
|
|
49
45
|
|