Fix task auto-completion (#50, #51)

[artemchege]

Summary

This PR implements automatic completion tracking

Changes

🔧 Fix subtask completion marking (#51)

Problem: The /awos:implement command didn't properly mark nested subtasks when they were completed.

Solution: Updated Step 5 in commands/implement.md with explicit instructions:

• Mark only the specific completed subtask
• Check if all subtasks under a parent are complete
• Automatically mark the parent task when all children are done

✅ Auto-mark acceptance criteria and roadmap items (#50)

Problem: After completing all tasks in a spec, users had to manually mark acceptance criteria and roadmap items as done, which was easy to forget and caused inconsistency.

Solution: Added new Step 6 to commands/implement.md:

• Automatically detect when all tasks in a spec are complete
• Mark all acceptance criteria in functional-spec.md as done
• Mark the corresponding roadmap item in roadmap.md as complete
• Notify user that the spec is fully implemented

📚 Documentation

• Updated README.md
• Improved /awos:implement description to mention auto-completion
• Added usage examples and anti-patterns

Closes #50
Closes #51

[workshur]

@copilot please fix prettier errors here

[Copilot]

@workshur I've opened a new pull request, #74, to work on those changes. Once the pull request is ready, I'll request review from you.

[mkf-simpson]

This requires more detailed discussions:

• Do we really want to "handoff" all specs? Can it hurt if there are many teammates work in the same repo with multiple specs? I mean, probably, we should give the team an ability to decide what specs should stay and what should be archived.
• If we have a handoff command, why do we check the roadmap on the implementation step? Considering that /awos:implement can be called step by step, it doesn't make sense to check the roadmap every time. (And I'm afraid, the model will be too optimistic).
• The overall flow is not clear for me. I think it should be like: spec -> tech -> implement -> hot fixes -> handoff (check completion / mark checkboxes / archive docs / update the state).

[mkf-simpson]

Oh, and if a spec changes architecture or product definition, the handoff command should make those changes in docs.

[artemchege]

Do we really want to "handoff" all specs?

We can "parametrize it", so the command will accept a particular spec for compression, otherwise do compression for all specs if none provided.

Can it hurt if there are many teammates work in the same repo with multiple specs?

If some teammates are working on unfinished specs, they won’t be compressed because there will most likely be unfinished tasks.

If we have a handoff command, why do we check the roadmap on the implementation step?

I was addressing this issue: #50

The problem is that after we trigger the implement command, it marks checkboxes in tasks files, but always forgets to mark specs and roadmap as finished.
This problem is always present in the project I develop locally using AWOS.

Probably I should have split this PR into 2:

• Where I introduce the handoff command
• Where I fix the /implement command

(And I'm afraid, the model will be too optimistic

We have a very strict set of instructions, that make the whole process less subjective: the LLM must check the checkboxes.

The overall flow is not clear for me. I think it should be like: spec -> tech -> implement -> hot fixes -> handoff (check completion / mark checkboxes / archive docs / update the state).

The main reason we mark checkboxes in /awos:implement instead of /awos:handoff comes down to two problems:

Problem 1: Roadmap becomes stale

If we only mark things in handoff, the roadmap would lie between completing a spec and running handoff. For example, you finish spec 001 on Monday, but the roadmap still shows Feature A as incomplete. You work on other specs for a week. Next Monday you run handoff and only then the roadmap shows Feature A as complete. The roadmap would be out of sync for days or weeks, which defeats its purpose as a source of truth.

Problem 2: Handoff is optional

Issue #50 specifically asks for automation so users don't forget to mark items. If we put marking in handoff, users might never run it (it's an optional cleanup command) or they can still forget, so issue #50 wouldn't be solved.

The current design separates concerns: /awos:implement marks completion immediately when the last task in a spec finishes (solves #50), while /awos:handoff archives already-completed specs into compact summaries (solves #20).

The completion check in implement is mechanical, not subjective - it just checks if all checkboxes in tasks.md are marked [x]. It only triggers once per spec when truly complete, so calling implement repeatedly isn't a problem, it just skips the check until the final task.

This keeps the roadmap accurate in real-time and makes handoff a true optional milestone cleanup, not a required workflow step.

Oh, and if a spec changes architecture or product definition, the handoff command should make those changes in docs.

Good point to consider, but I think this falls outside the scope of handoff.
Handoff is about archival, not synchronization. It's designed to collect already-completed work, compact the details into summaries, and prepare for the next milestone. It shouldn't manage changes to strategic documents like architecture or product definition.

TL:DR I think everything is ok as is. The implement command now is more correct and it makes as completed not only tasks, but also specs and roadmap, making it always up to date and accurate.
The handoff command is simple and does one thing only: it does archiving only.

@workshur share your opinion please once you are back.

[mkf-simpson]

Ok, there are more than one conversation now :) Let's start with the flow first.

1. You make a new spec
2. You implement it
3. When it's done (btw what is "done"? marked checkboxes? met acceptance criteria?), you have to update the current state: your CLAUDE.md files / architecture / product definition.
4. Go to 1
5. ...
6. Archive everything you don't need anymore

Hand-off itself, imo, is something where you pass the result of your work with all the documentation. So, probably, it is just a naming crisis: handoff should be on the spec-level, and this one should be archive or something.

Handoff is about archival, not synchronization.

[artemchege]

@mkf-simpson
I dropped the handoff functionality, lets merge the fixes for #50 and #51 first and discuss the handoff functionality separately

[Mgrdich]

should we change the Status of the functional-spec.md as well ? Completed

The status essentially tracks: Draft → In Review → Approved → Completed